azeroth-shell 0.0.0-stage → 0.1.0

package/src/domain/bots/botPool.ts

@@ -0,0 +1,291 @@
+// The world's random-bot population — 5000 deterministic bots on a FIXED world seed, so every
+// player meets the same ones. Race/class follow the baked census weights. Pure: no clock, no rng.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { Faction } from '../../data/schema.ts';
+import { hashSeed } from '../../engine/core/rng.ts';
+import { factionOf } from '../character/races.ts';
+import { companionGender, stableIdHash } from './squad.ts';
+import { pickSpecIndex } from '../character/talentLink.ts';
+import type { GearProfile } from './botGear.ts';
+import { isRaidGearProfile } from './botGear.ts';
+import { hireCostCopper, isCheapHireProfile } from './companionHireCost.ts';
+
+export const WORLD_BOT_COUNT = 5000;
+export const MAX_BOT_LEVEL = 60;
+/** Inn hire window half-width: bots within ±2 levels of the player. */
+export const HIRE_LEVEL_WINDOW = 2;
+// How many candidates an innkeeper puts forward. 16, not 8: a raid roster is 40 bodies of specific
+// classes, and eight faces per bracket meant zone-hopping to assemble one.
+export const INN_SLATE_SIZE = 16;
+// 15% of the pool sits at max level whatever the stripe rolled: RandomPlayerbotMgr.cpp:2861
+// (AiPlayerbot.RandomBotMaxLevelChance = 0.15, aiplayerbot.conf.dist.in:132).
+export const MAX_LEVEL_CHANCE_PCT = 15;
+
+/** Fixed world seed — the population is the same in every save. */
+const WORLD_SEED = stableIdHash('phonecraft-botworld-1');
+
+export interface WorldBot {
+  /** Stable id: 'b' + pool index. */
+  id: string;
+  index: number;
+  name: string;
+  gender: 0 | 1;
+  race: number;
+  cls: number;
+  faction: Faction | undefined;
+  /** Base level (static population; a hired bot levels through XP in your party). */
+  level: number;
+  /** Index into ds.botSpecs(cls) — the premade build this bot runs. */
+  specIdx: number;
+  /** Per-bot stream seed (spawn gear, flavor). */
+  seed: number;
+}
+
+// ---- population build (once per DataStore) ----------------------------------
+
+const POOL_CACHE = new WeakMap<DataStore, WorldBot[]>();
+
+/** Valid race/class combos with their census weight (create-info validated). */
+function weightedCombos(ds: DataStore): { race: number; cls: number; w: number }[] {
+  const probs = ds.botPopulation();
+  const out: { race: number; cls: number; w: number }[] = [];
+  for (const r of ds.races()) {
+    for (const cls of r.classes) {
+      if (!ds.createInfo(r.id, cls)) continue;
+      const w = probs[`${cls}.${r.id}`];
+      out.push({ race: r.id, cls, w: Math.max(1, w ?? 20) }); // conf default when unlisted
+    }
+  }
+  return out;
+}
+
+// The full world population: levels stripe 1..60 plus the 15% max-level bulge, race/class ride
+// the census weights, names are unique per gender until the pool wraps. Deterministic, cached.
+export function worldBots(ds: DataStore): WorldBot[] {
+  const cached = POOL_CACHE.get(ds);
+  if (cached) return cached;
+  const combos = weightedCombos(ds);
+  const totalW = combos.reduce((s, c) => s + c.w, 0);
+  const names = ds.botNames();
+  const counters: [number, number] = [0, 0]; // per-gender name cursor
+  const bots: WorldBot[] = [];
+  if (combos.length === 0) {
+    POOL_CACHE.set(ds, bots);
+    return bots;
+  }
+  for (let i = 0; i < WORLD_BOT_COUNT; i++) {
+    const seed = hashSeed(WORLD_SEED, i);
+    let roll = Math.abs(seed) % totalW;
+    let combo = combos[combos.length - 1]!;
+    for (const c of combos) {
+      roll -= c.w;
+      if (roll < 0) { combo = c; break; }
+    }
+    const gender = companionGender(seed);
+    const list = gender === 1 ? names.female : names.male;
+    const cursor = counters[gender]++;
+    const name = list.length === 0
+      ? `Bot ${i}`
+      : `${list[cursor % list.length]!}${cursor >= list.length ? ` ${'II III IV V'.split(' ')[Math.floor(cursor / list.length) - 1] ?? 'VI'}` : ''}`;
+    let level = 1 + (i % MAX_BOT_LEVEL);
+    if (level < MAX_BOT_LEVEL
+      && Math.abs(hashSeed(seed, 9)) % 100 < MAX_LEVEL_CHANCE_PCT) level = MAX_BOT_LEVEL;
+    bots.push({
+      id: `b${i}`,
+      index: i,
+      name,
+      gender,
+      race: combo.race,
+      cls: combo.cls,
+      faction: factionOf(ds, combo.race),
+      level,
+      specIdx: pickSpecIndex(ds.botSpecs(combo.cls), hashSeed(seed, 5)) ?? 0,
+      seed,
+    });
+  }
+  POOL_CACHE.set(ds, bots);
+  return bots;
+}
+
+/** A bot's role, read off the premade build it runs. */
+export function worldBotRole(ds: DataStore, b: WorldBot): string {
+  const spec = ds.botSpecs(b.cls)[b.specIdx];
+  return spec?.role ?? 'dps';
+}
+
+export interface BotSearchFilters {
+  /** Class ids. Empty / absent ⇒ any. */
+  classes?: readonly number[];
+  /** 'tank' | 'healer' | 'dps'. Empty / absent ⇒ any. */
+  roles?: readonly string[];
+  minLevel?: number;
+  maxLevel?: number;
+  /** Gear tiers (as rolled for this zone/bracket salt). Empty / absent ⇒ any. */
+  tiers?: readonly GearProfile[];
+  /** Copper ceiling on the hire price. 0 / absent ⇒ any. */
+  maxCostCopper?: number;
+  /** Case-insensitive substring of the bot's name. */
+  name?: string;
+  /** Hard result cap. Default 24. */
+  limit?: number;
+}
+
+/** True when at least one filter would actually narrow the pool. */
+export function hasBotSearchFilter(f: BotSearchFilters | undefined): boolean {
+  if (!f) return false;
+  return !!(f.classes?.length || f.roles?.length || f.tiers?.length
+    || (f.minLevel != null && f.minLevel > 1)
+    || (f.maxLevel != null && f.maxLevel < MAX_BOT_LEVEL)
+    || (f.maxCostCopper != null && f.maxCostCopper > 0)
+    || (f.name && f.name.trim().length > 0));
+}
+
+// Search the whole same-faction population instead of one innkeeper's slate. Returns [] when
+// nothing is filtered — 2500 bots is not a shortlist. Level is not clamped to the hire window.
+export function searchWorldBots(args: {
+  ds: DataStore;
+  playerRace: number;
+  playerLevel: number;
+  zoneId: string;
+  excludeIds?: readonly string[];
+  filters: BotSearchFilters;
+}): WorldBot[] {
+  const { ds, filters: f } = args;
+  if (!hasBotSearchFilter(f)) return [];
+  const team = factionOf(ds, args.playerRace);
+  const excluded = new Set(args.excludeIds ?? []);
+  const salt = innZoneSalt(args.zoneId, args.playerLevel);
+  const clsSet = f.classes?.length ? new Set(f.classes) : null;
+  const roleSet = f.roles?.length ? new Set(f.roles) : null;
+  const tierSet = f.tiers?.length ? new Set<GearProfile>(f.tiers) : null;
+  const q = f.name?.trim().toLowerCase() ?? '';
+  const lo = Math.max(1, f.minLevel ?? 1);
+  const hi = Math.min(MAX_BOT_LEVEL, f.maxLevel ?? MAX_BOT_LEVEL);
+  const limit = Math.max(1, f.limit ?? 24);
+
+  const out: WorldBot[] = [];
+  for (const b of worldBots(ds)) {
+    if (b.faction !== team || excluded.has(b.id)) continue;
+    if (b.level < lo || b.level > hi) continue;
+    if (clsSet && !clsSet.has(b.cls)) continue;
+    if (q && !b.name.toLowerCase().includes(q)) continue;
+    if (roleSet && !roleSet.has(worldBotRole(ds, b))) continue;
+    if (tierSet || (f.maxCostCopper != null && f.maxCostCopper > 0)) {
+      const profile = pickProfile(b.id, salt, args.playerLevel);
+      if (tierSet && !tierSet.has(profile)) continue;
+      if (f.maxCostCopper != null && f.maxCostCopper > 0
+        && hireCostCopper(b.level, profile) > f.maxCostCopper) continue;
+    }
+    out.push(b);
+    if (out.length >= limit) break;
+  }
+  return out.sort((x, y) => x.level - y.level || x.index - y.index);
+}
+
+/** Pool bot by id ('b<index>'), or undefined. */
+export function worldBot(ds: DataStore, id: string): WorldBot | undefined {
+  if (!id.startsWith('b')) return undefined;
+  const idx = Number(id.slice(1));
+  if (!Number.isInteger(idx) || idx < 0 || idx >= WORLD_BOT_COUNT) return undefined;
+  return worldBots(ds)[idx];
+}
+
+// Stable inn salt: zone id + 5-level player bracket (same as innSlate rotation). ICH3 pickProfile uses this
+// so kit tiers stay fixed for a visit band.
+export function innZoneSalt(zoneId: string, playerLevel: number): number {
+  return hashSeed(stableIdHash(zoneId), Math.floor(Math.max(1, playerLevel) / 5));
+}
+
+// ICH3 kit profile for a slate face. Below player level 55 it biases naked/shabby/field/twink and
+// never raid; at 55+ it uses the high-level mix. Slate-level guarantees come from the post-pass.
+export function pickProfile(
+  botId: string,
+  zoneSalt: number,
+  playerLevel: number,
+): GearProfile {
+  const idx = botId.startsWith('b')
+    ? Number(botId.slice(1))
+    : stableIdHash(botId);
+  const seedIdx = Number.isFinite(idx) ? idx : stableIdHash(botId);
+  const roll = Math.abs(hashSeed(zoneSalt, seedIdx * 17 + 3)) % 100;
+  const lvl = Math.max(1, Math.min(60, Math.floor(playerLevel)));
+
+  // Mid-level inns (design §5.2 rule 3): no raid-*.
+  if (lvl < 55) {
+    // Weights: naked 10%, shabby 30%, field 40%, twink 20%
+    if (roll < 10) return 'naked';
+    if (roll < 40) return 'shabby';
+    if (roll < 80) return 'field';
+    return 'twink';
+  }
+
+  // L55+ mix among ~8 faces (design §5.2 shares):
+  // naked 1–2, shabby 2–3, field 2–3, twink 0–1, raid-mixed 0–1, t2/t3 rare.
+  if (roll < 15) return 'naked';
+  if (roll < 45) return 'shabby';
+  if (roll < 75) return 'field';
+  if (roll < 85) return 'twink';
+  if (roll < 93) return 'raid-mixed';
+  if (roll < 98) return 'raid-t2';
+  return 'raid-t3';
+}
+
+// Slate stratification post-pass: at high level guarantee one cheap face and never an all-raid
+// slate; at mid level strip any raid profile that slipped through.
+export function ensureSlateProfileMix(
+  profiles: readonly GearProfile[],
+  zoneSalt: number,
+  playerLevel: number,
+): GearProfile[] {
+  if (profiles.length === 0) return [];
+  const out = profiles.slice();
+  const lvl = Math.max(1, Math.min(60, Math.floor(playerLevel)));
+
+  if (lvl < 55) {
+    for (let i = 0; i < out.length; i++) {
+      if (isRaidGearProfile(out[i]!)) out[i] = 'field';
+    }
+    return out;
+  }
+
+  if (!out.some(isCheapHireProfile)) {
+    const i = Math.abs(hashSeed(zoneSalt, 777)) % out.length;
+    out[i] = (Math.abs(hashSeed(zoneSalt, 778)) % 2 === 0) ? 'naked' : 'shabby';
+  }
+
+  if (out.every((p) => isRaidGearProfile(p))) {
+    out[0] = 'shabby';
+  }
+  return out;
+}
+
+// The innkeeper's slate: same-faction bots within ±HIRE_LEVEL_WINDOW, widening a level at a time
+// up to ±9 so edge brackets stay hirable. `excludeIds` drops anyone already in the roster.
+export function innSlate(args: {
+  ds: DataStore;
+  playerRace: number;
+  playerLevel: number;
+  zoneId: string;
+  excludeIds?: readonly string[];
+}): WorldBot[] {
+  const { ds } = args;
+  const team = factionOf(ds, args.playerRace);
+  const excluded = new Set(args.excludeIds ?? []);
+  const all = worldBots(ds).filter((b) => b.faction === team && !excluded.has(b.id));
+  let halfSpan = HIRE_LEVEL_WINDOW;
+  let fits: WorldBot[] = [];
+  for (; halfSpan <= 9; halfSpan++) {
+    fits = all.filter((b) => Math.abs(b.level - args.playerLevel) <= halfSpan);
+    if (fits.length >= INN_SLATE_SIZE) break;
+  }
+  // Stable per-zone/bracket rotation: same inn shows the same faces for a
+  // 5-level bracket, other inns show different ones.
+  const salt = innZoneSalt(args.zoneId, args.playerLevel);
+  return fits
+    .map((b) => ({ b, k: Math.abs(hashSeed(salt, b.index)) }))
+    .sort((x, y) => x.k - y.k || x.b.index - y.b.index)
+    .slice(0, INN_SLATE_SIZE)
+    .map((x) => x.b)
+    .sort((x, y) => x.level - y.level || x.index - y.index);
+}

package/src/domain/bots/botProfessions.ts

@@ -0,0 +1,334 @@
+// World-bot trade skills — the playerbots profession half, with exactly two complementary
+// primaries, one secondary, and an enchanting rod tier that matches skill. Pure and deterministic.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { SkillLine } from '../../data/schema.ts';
+import type { Character } from '../character/character.ts';
+import type { Inventory } from '../items/inventory.ts';
+import { addItem, countItem } from '../items/inventory.ts';
+import { rankUpReqSkill } from '../professions/professions.ts';
+import type { Rng } from '../../engine/core/rng.ts';
+import { mulberry32, hashSeed } from '../../engine/core/rng.ts';
+
+/** Seed salt for profession RNG stream — ASCII "prof". */
+export const PROFESSION_SEED_SALT = 0x70726f66;
+
+// ---- Complementary primary pairs (product list; must include classic matches) ----
+
+/** Two distinct primary skill lines that complement each other. */
+export type PrimaryPair = readonly [SkillLine, SkillLine];
+
+// Allowed complementary pairs for a Random Character, picked uniformly: mining+BS, mining+eng,
+// herbalism+alchemy, skinning+LW, tailoring+enchanting, plus two double-gather variants.
+export const COMPLEMENTARY_PRIMARY_PAIRS: readonly PrimaryPair[] = [
+  ['mining', 'blacksmithing'],
+  ['mining', 'engineering'],
+  ['herbalism', 'alchemy'],
+  ['skinning', 'leatherworking'],
+  ['tailoring', 'enchanting'],
+  ['herbalism', 'enchanting'],
+  ['mining', 'herbalism'],
+];
+
+/** Secondaries — pick exactly one (product: not all three like playerbots). */
+export const SECONDARY_SKILLS: readonly SkillLine[] = ['cooking', 'firstaid', 'fishing'];
+
+// ---- Tool item entries (PlayerbotFactory::InitInventorySkill) ----------------
+
+/** Mining Pick. */
+export const TOOL_MINING_PICK = 2901;
+/** Blacksmith Hammer — BS or engineering. */
+export const TOOL_BLACKSMITH_HAMMER = 5956;
+/** Arclight Spanner — engineering. */
+export const TOOL_ARCLIGHT_SPANNER = 6219;
+/** Skinning Knife. */
+export const TOOL_SKINNING_KNIFE = 7005;
+/** Fishing Pole (product: bags only; not auto-equip ranged). */
+export const TOOL_FISHING_POLE = 6256;
+
+// Enchanting rods by min skill, an improvement over always-Arcanite: the highest tier whose
+// minSkill ≤ current enchanting wins. Cite: profession-data.json enchantRods.
+export const ENCHANTING_ROD_TIERS: readonly { minSkill: number; entry: number }[] = [
+  { minSkill: 290, entry: 16207 }, // Runed Arcanite Rod
+  { minSkill: 200, entry: 11145 }, // Runed Truesilver Rod
+  { minSkill: 150, entry: 11130 }, // Runed Golden Rod
+  { minSkill: 100, entry: 6339 },  // Runed Silver Rod
+  { minSkill: 0, entry: 6218 },    // Runed Copper Rod
+];
+
+// ---- SetRandomSkill classic profession caps ---------------------------------
+
+// Profession skill max at character level — PlayerbotFactory::SetRandomSkill classic / MANGOSBOT_ZERO
+// branch (level gates 35 / 20 / 10).
+export function professionSkillCap(level: number): number {
+  const lvl = Math.max(1, Math.min(60, level | 0));
+  if (lvl >= 35) return 300;
+  if (lvl >= 20) return 225;
+  if (lvl >= 10) return 150;
+  return 75;
+}
+
+// ---- Trainer rank ladder (what a profession trainer teaches a companion) ----
+
+/** A rung a companion trains at a profession trainer: it is the cap, not a recipe. */
+export interface CompanionRank {
+  rank: number;
+  name: string;
+  cap: number;
+  /** Character level the trainer demands (secondaries open Apprentice at 1). */
+  reqLevel: number;
+  secondaryReqLevel: number;
+}
+
+// The four rungs every 1.12 profession shares, from profession-data.json `ranks` (all 12 lines carry
+// the same caps and reqLevels). src/dev/capabilities/companionTrainerRanks.mjs holds it to the bake.
+export const PROFESSION_RANK_LADDER: readonly CompanionRank[] = [
+  { rank: 1, name: 'Apprentice', cap: 75, reqLevel: 5, secondaryReqLevel: 1 },
+  { rank: 2, name: 'Journeyman', cap: 150, reqLevel: 10, secondaryReqLevel: 10 },
+  { rank: 3, name: 'Expert', cap: 225, reqLevel: 20, secondaryReqLevel: 20 },
+  { rank: 4, name: 'Artisan', cap: 300, reqLevel: 35, secondaryReqLevel: 35 },
+];
+
+/** Lines whose Apprentice rank opens at level 1 (cooking, first aid, fishing). */
+function isSecondaryLine(line: SkillLine): boolean {
+  return SECONDARY_SKILLS.includes(line);
+}
+
+// Highest rank a companion holds: each rung needs the trainer's level gate and, past Apprentice, the
+// skill the player pays too (cap - 25 => 50/125/200). Free, like their trainer/vendor recipe catalog.
+export function companionTrainedRank(
+  line: SkillLine,
+  skill: number,
+  level: number,
+): CompanionRank | undefined {
+  const lvl = Math.max(1, Math.min(60, level | 0));
+  const value = Math.max(0, skill | 0);
+  const secondary = isSecondaryLine(line);
+  let held: CompanionRank | undefined;
+  for (const rung of PROFESSION_RANK_LADDER) {
+    if (lvl < (secondary ? rung.secondaryReqLevel : rung.reqLevel)) break;
+    if (held && value < rankUpReqSkill(held.cap)) break;
+    held = rung;
+  }
+  return held;
+}
+
+// Ceiling a companion actually holds: their trained rank, never above the level cap. 0 = not yet
+// trainable (a primary before level 5). Poisons is quest-learned and keeps the level cap.
+export function companionSkillCap(line: SkillLine, skill: number, level: number): number {
+  if (line === 'poisons') return professionSkillCap(level);
+  const rank = companionTrainedRank(line, skill, level);
+  return rank ? Math.min(professionSkillCap(level), rank.cap) : 0;
+}
+
+// Re-cap a skill map against the ranks trained. A line with no rank yet is dropped — an untrained
+// profession is not a profession.
+export function applyTrainedCaps(
+  skills: Character['skills'],
+  level: number,
+): Character['skills'] {
+  const out: Character['skills'] = {};
+  for (const [key, cur] of Object.entries(skills) as Array<[SkillLine, { current: number; max: number } | undefined]>) {
+    if (!cur) continue;
+    const cap = companionSkillCap(key, cur.current, level);
+    if (cap <= 0) continue;
+    out[key] = { current: Math.max(1, Math.min(cap, cur.current)), max: cap };
+  }
+  return out;
+}
+
+// `urand(maxValue - level, maxValue)` then SetSkill(id, value, maxValue). Lo clamped to ≥ 1 when maxValue -
+// level would be ≤ 0.
+export function rollProfessionSkill(
+  level: number,
+  rng: Rng,
+): { current: number; max: number } {
+  const lvl = Math.max(1, Math.min(60, level | 0));
+  const maxValue = professionSkillCap(lvl);
+  const lo = Math.max(1, maxValue - lvl);
+  const hi = maxValue;
+  const current = lo > hi ? hi : rng.int(lo, hi);
+  return { current, max: maxValue };
+}
+
+export function pickPrimaryPair(rng: Rng): PrimaryPair {
+  const i = rng.int(0, COMPLEMENTARY_PRIMARY_PAIRS.length - 1);
+  return COMPLEMENTARY_PRIMARY_PAIRS[i]!;
+}
+
+export function pickSecondary(rng: Rng): SkillLine {
+  const i = rng.int(0, SECONDARY_SKILLS.length - 1);
+  return SECONDARY_SKILLS[i]!;
+}
+
+/** Highest enchanting rod the skill value qualifies for. */
+export function rodForEnchantingSkill(skill: number): number {
+  const v = Math.max(0, skill | 0);
+  for (const tier of ENCHANTING_ROD_TIERS) {
+    if (v >= tier.minSkill) return tier.entry;
+  }
+  return 6218;
+}
+
+// ---- InitInventorySkill tools -----------------------------------------------
+
+function storeOne(inv: Inventory, entry: number, ds: DataStore): Inventory {
+  if (countItem(inv, entry) > 0) return inv;
+  const it = ds.item(entry);
+  if (!it) return inv;
+  return addItem(inv, entry, 1, it.stackable ?? 1);
+}
+
+// PlayerbotFactory::InitInventorySkill — grant profession tools into bags when char.skills already
+// has the matching lines. Idempotent, and the fishing pole stays in bags rather than equipped.
+export function initInventorySkill(
+  char: Character,
+  inv: Inventory,
+  ds: DataStore,
+): Inventory {
+  let out = inv;
+  const sk = char.skills;
+  if (sk.mining) out = storeOne(out, TOOL_MINING_PICK, ds);
+  if (sk.blacksmithing || sk.engineering) out = storeOne(out, TOOL_BLACKSMITH_HAMMER, ds);
+  if (sk.engineering) out = storeOne(out, TOOL_ARCLIGHT_SPANNER, ds);
+  if (sk.skinning) out = storeOne(out, TOOL_SKINNING_KNIFE, ds);
+  if (sk.fishing) out = storeOne(out, TOOL_FISHING_POLE, ds);
+  if (sk.enchanting) {
+    out = storeOne(out, rodForEnchantingSkill(sk.enchanting.current), ds);
+  }
+  return out;
+}
+
+// ---- Trainer recipes / enchants ---------------------------------------------
+
+// Auto-grant trainer + vendor catalog recipes/enchants the skill can already use. Drop recipes are never
+// granted (those need the item). Used by playerbots kits and companion profession sync.
+export function learnNpcCatalog(
+  char: Character,
+  lines: SkillLine[],
+  ds: DataStore,
+): Character {
+  const known = new Set(char.knownRecipes);
+  const knownEnch = new Set(char.knownEnchants ?? []);
+  const skillOf = (line: SkillLine): number => char.skills[line]?.current ?? 0;
+  // npc_trainer.reqlevel (poison ranks). Unknown level = no gate, as before.
+  const lvl = typeof char.level === 'number' ? char.level : Infinity;
+
+  for (const line of lines) {
+    const v = skillOf(line);
+    if (v <= 0) continue;
+    for (const r of ds.recipes()) {
+      if (r.skill !== line) continue;
+      // trainer + vendor only — never drop/quest recipe items.
+      if (r.source !== 'trainer' && r.source !== 'vendor') continue;
+      if (r.orange > v) continue;
+      if ((r.reqLevel ?? 0) > lvl) continue;
+      known.add(r.id);
+    }
+    if (line === 'enchanting') {
+      for (const e of ds.enchants()) {
+        if (e.source !== 'trainer' && e.source !== 'vendor') continue;
+        if (e.orange > v) continue;
+        knownEnch.add(e.id);
+      }
+    }
+  }
+
+  return {
+    ...char,
+    knownRecipes: [...known],
+    knownEnchants: [...knownEnch],
+  };
+}
+
+/** @deprecated alias — use learnNpcCatalog (now includes vendor rows). */
+function learnTrainerRecipes(
+  char: Character,
+  lines: SkillLine[],
+  ds: DataStore,
+): Character {
+  return learnNpcCatalog(char, lines, ds);
+}
+
+// Sync a companion's knownRecipes / knownEnchants from their skill map. Mutates the companion in place.
+// Free catalog only (trainer + vendor).
+export function syncCompanionProfessionCatalog(
+  comp: { knownRecipes?: number[]; knownEnchants?: number[]; level?: number },
+  skills: Character['skills'],
+  ds: DataStore,
+): void {
+  const lines = Object.keys(skills) as SkillLine[];
+  if (!lines.length) return;
+  // Minimal shell — learnNpcCatalog only reads skills + known* lists.
+  const shell = {
+    skills,
+    level: comp.level,
+    knownRecipes: [...(comp.knownRecipes ?? [])],
+    knownEnchants: [...(comp.knownEnchants ?? [])],
+  } as Character;
+  const next = learnNpcCatalog(shell, lines, ds);
+  comp.knownRecipes = next.knownRecipes;
+  comp.knownEnchants = next.knownEnchants;
+}
+
+// ---- Public: apply full profession kit --------------------------------------
+
+export interface BotProfessionResult {
+  char: Character;
+  inventory: Inventory;
+  primaries: [SkillLine, SkillLine];
+  secondary: SkillLine;
+}
+
+// Just the skill lines a companion trained — no recipes, tools or inventory, because
+// companionCharacter runs on every rotation build. `maxed` stamps each line at its level cap.
+export function companionProfessionSkills(
+  seed: number,
+  level: number,
+  opts: { maxed?: boolean } = {},
+): Character['skills'] {
+  const rng = mulberry32(hashSeed(seed, PROFESSION_SEED_SALT));
+  const pair = pickPrimaryPair(rng);
+  const secondary = pickSecondary(rng);
+  const lvl = Math.max(1, Math.min(60, level | 0));
+  const cap = professionSkillCap(lvl);
+  const skills: Character['skills'] = {};
+  for (const line of [pair[0], pair[1], secondary] as const) {
+    skills[line] = opts.maxed ? { current: cap, max: cap } : rollProfessionSkill(lvl, rng);
+  }
+  return skills;
+}
+
+export function applyBotProfessions(
+  char: Character,
+  inv: Inventory,
+  seed: number,
+  ds: DataStore,
+): BotProfessionResult {
+  const rng = mulberry32(hashSeed(seed, PROFESSION_SEED_SALT));
+  const pair = pickPrimaryPair(rng);
+  const secondary = pickSecondary(rng);
+  const level = Math.max(1, Math.min(60, char.level | 0));
+
+  // Stamp skills: primary0, primary1, secondary (stable RNG order).
+  const skills: Character['skills'] = { ...char.skills };
+  for (const line of [pair[0], pair[1], secondary] as const) {
+    skills[line] = rollProfessionSkill(level, rng);
+  }
+
+  let next: Character = {
+    ...char,
+    skills,
+    knownRecipes: [...(char.knownRecipes ?? [])],
+    knownEnchants: [...(char.knownEnchants ?? [])],
+  };
+  next = learnTrainerRecipes(next, [pair[0], pair[1], secondary], ds);
+  const inventory = initInventorySkill(next, inv, ds);
+
+  return {
+    char: next,
+    inventory,
+    primaries: [pair[0], pair[1]],
+    secondary,
+  };
+}