azeroth-shell 0.0.0-stage → 0.1.0

package/src/domain/bg/avInstanceScore.ts

@@ -0,0 +1,123 @@
+/**
+ * Alterac Valley's reinforcement race, for the instance surface.
+ *
+ * `av.ts` runs the full battleground on `BgWorld` — nodes, mines, graveyard cycle, the lot. The
+ * raid surface has none of that machinery and does not need most of it: on a push the score moves
+ * on exactly three things, and all three are already state the instance run keeps.
+ *
+ *   - a tower falls        -75  its owner   (BattleGroundAV.h:62 BG_AV_RES_TOWER)
+ *   - a captain dies      -100  their team  (BattleGroundAV.h:57 BG_AV_RES_CAPTAIN)
+ *   - one of yours dies     -1  your team   (BattleGroundAV.cpp:38-45 HandleKillPlayer)
+ *
+ * and the general's death ends it outright (BattleGroundAV.cpp:57), which on this surface IS the
+ * run completing, because the general is the last encounter.
+ *
+ * So this is a PURE READ of the run: the cleared encounter ids give the enemy's losses and
+ * `avDeaths` gives yours. Nothing here ticks, holds state, or has to be kept in sync — a re-mount
+ * recomputes the same number from the same `defeated` list.
+ *
+ * NOT MODELLED HERE, and deliberately: the mines' one-reinforcement-per-45s tick and node capture
+ * (BattleGroundAV.cpp:319-341, :645/:687). Those need an owner per node and a clock, which is the
+ * battleground screen's job and the next thing to port.
+ */
+
+import type { InstanceDef } from '../../data/schema/encounter.ts';
+import type { InstanceRun } from '../../world/instances.ts';
+import { isCleared } from '../../world/instances.ts';
+import {
+  AV_RES_CAPTAIN, AV_RES_TOWER, AV_SCORE_INITIAL_POINTS, AV_SCORE_NEAR_LOSE,
+} from './av.ts';
+import type { AvTeam } from '../../data/alteracValley.ts';
+import { avMineBoard, avNodeBoard } from './avInstanceNodes.ts';
+import { avEnemyStateAt, type AvEnemyState } from './avEnemyPush.ts';
+
+export interface AvInstanceScore {
+  /** The side the player's raid is on — the def's own wing. */
+  team: AvTeam;
+  foe: AvTeam;
+  /** Reinforcements left, both sides, against `initial`. */
+  own: number;
+  enemy: number;
+  initial: number;
+  /** Under BG_AV_NEAR_LOSE — the point the client starts warning. */
+  ownNearLose: boolean;
+  enemyNearLose: boolean;
+  /** Towers of the foe's this raid has taken, and whether the captain is down. */
+  towersDown: number;
+  captainDown: boolean;
+  /** Graveyards this side holds outright, and mines paying into `own`. */
+  graveyardsHeld: number;
+  minesHeld: number;
+  /** The other side's push: what they have taken, what they are on, and whether they won. */
+  enemyPush: AvEnemyState;
+}
+
+/** An AV wing def, by the id `alterac-valley.ts` builds. */
+export function isAvInstance(instanceId: string): boolean {
+  return instanceId === 'alterac-valley-alliance' || instanceId === 'alterac-valley-horde';
+}
+
+function teamOf(def: InstanceDef): AvTeam | null {
+  if (!isAvInstance(def.id)) return null;
+  return def.wing === 'horde' ? 'horde' : 'alliance';
+}
+
+/**
+ * The reinforcement race for this run, or null when the def is not an AV wing.
+ *
+ * Encounter ids are `captain-<entry>` / `lieutenant-<entry>` / `general-<entry>`, which
+ * `commandersOf` builds off the creature entry — the DB's own key, stable across bakes.
+ */
+export function avInstanceScore(
+  def: InstanceDef,
+  run: InstanceRun,
+  /** Run clock, ms. Drives the enemy push; omit for a board with no opposing raid. */
+  elapsedMs = 0,
+): AvInstanceScore | null {
+  const team = teamOf(def);
+  if (!team) return null;
+  const foe: AvTeam = team === 'alliance' ? 'horde' : 'alliance';
+
+  let towersDown = 0;
+  let captainDown = false;
+  for (const enc of def.encounters) {
+    if (!isCleared(run, enc.id)) continue;
+    if (enc.id.startsWith('lieutenant-')) towersDown++;
+    else if (enc.id.startsWith('captain-')) captainDown = true;
+  }
+
+  const enemy = Math.max(
+    0,
+    AV_SCORE_INITIAL_POINTS - towersDown * AV_RES_TOWER - (captainDown ? AV_RES_CAPTAIN : 0),
+  );
+  // Your own bar: one off per death, one BACK per mine tick you have banked. Cite:
+  // BattleGroundAV.cpp:38-45 HandleKillPlayer; :319-341 the 45 s mine tick. Never above the start,
+  // because UpdateScore clamps and a side cannot bank past its opening reinforcements.
+  // ...and the other side's push takes YOUR towers and captain on its own clock, which is what
+  // makes this a race rather than a one-sided countdown. avEnemyPush.ts owns that cursor.
+  const push = avEnemyStateAt(team, elapsedMs);
+  const own = Math.max(0, Math.min(
+    AV_SCORE_INITIAL_POINTS,
+    AV_SCORE_INITIAL_POINTS
+      - Math.max(0, run.avDeaths ?? 0)
+      - push.costSoFar
+      + Math.max(0, run.avMineIncome ?? 0),
+  ));
+
+  const board = avNodeBoard(run);
+  const mines = avMineBoard(run);
+  return {
+    enemyPush: push,
+    graveyardsHeld: board.filter((n) => n.owner === team && n.state === 'owned').length,
+    minesHeld: mines.filter((m) => m.owner === team).length,
+    team,
+    foe,
+    own,
+    enemy,
+    initial: AV_SCORE_INITIAL_POINTS,
+    ownNearLose: own < AV_SCORE_NEAR_LOSE,
+    enemyNearLose: enemy < AV_SCORE_NEAR_LOSE,
+    towersDown,
+    captainDown,
+  };
+}

package/src/domain/bg/avQuestItems.ts

@@ -0,0 +1,55 @@
+/**
+ * Alterac Valley quest items that belong to ONE faction, so the other side never loots them.
+ *
+ * ClassicDB z2815 is asymmetric here and our bake is faithful to it:
+ *
+ *   item 17306 "Blood"          (Horde, A Gallon of Blood / Lokholar)  126 rows, ALL -100 -> quest drop
+ *   item 17423 "Storm Crystal"  (Alliance, Crystal Cluster / Ivus)     129 rows, ALL  +80 -> PLAIN loot
+ *   item 17422 "Armor Scraps" / "Enemy Booty" (BOTH sides)             183 rows,      +80
+ *
+ * A positive ChanceOrQuestChance is not a quest drop, so `allowsQuestDrop` never runs on the
+ * Alliance rows and a Horde player loots Storm Crystals at 80% — which is what the operator saw.
+ * The Horde equivalent is gated correctly, so this cannot be fixed by treating the whole table
+ * one way: the lock has to come from WHOSE QUEST the item belongs to.
+ *
+ * That is exactly what `AV_DATA.quests` carries — every AV turn-in with its `team` and its `item`.
+ * An item used by both sides (17422 scraps/booty, and the two mine supply runs, which each side
+ * turns in at its own mine) stays open to everyone. An item used by ONE side is locked to it.
+ *
+ * Cite: BattleGroundAV.cpp:161-256 m_teamQuestStatus, baked to AV_DATA.quests.
+ */
+
+import { AV_QUESTS, type AvTeam } from '../../data/alteracValley.ts';
+
+/** item id -> the only team that may loot it. Absent = both sides may. */
+let lockedByItem: Map<number, AvTeam> | null = null;
+
+function build(): Map<number, AvTeam> {
+  const teamsOf = new Map<number, Set<AvTeam>>();
+  for (const q of AV_QUESTS) {
+    if (!q.item) continue;
+    let set = teamsOf.get(q.item);
+    if (!set) { set = new Set(); teamsOf.set(q.item, set); }
+    set.add(q.team);
+  }
+  const out = new Map<number, AvTeam>();
+  for (const [item, teams] of teamsOf) {
+    if (teams.size === 1) out.set(item, [...teams][0]!);
+  }
+  return out;
+}
+
+/** The team an AV quest item is locked to, or null when both sides use it (or it is not one). */
+export function avQuestItemTeam(itemId: number): AvTeam | null {
+  lockedByItem ??= build();
+  return lockedByItem.get(itemId) ?? null;
+}
+
+/**
+ * May `team` loot this item? True for everything that is not a one-faction AV quest item, so a
+ * caller can ask about every drop without knowing whether Alterac is involved.
+ */
+export function avAllowsLoot(itemId: number, team: AvTeam): boolean {
+  const locked = avQuestItemTeam(itemId);
+  return locked == null || locked === team;
+}

package/src/domain/bg/avQuests.ts

@@ -0,0 +1,210 @@
+// Alterac's war economy: what a body drops, what a team banks, and what the turn-ins buy.
+// Cite: BattleGroundAV.cpp:156-266 HandleQuestComplete (the nine counters and their thresholds);
+// `reference_loot_template` 1 (battleground_template.PlayerSkinReflootId — AV is the only BG where
+// an enemy player is lootable) and `creature_loot_template` for the field.
+
+import type { BgTeam } from './types.ts';
+import type { Rng } from '../../engine/core/rng.ts';
+import { AV_DATA } from '../../data/alteracValley.ts';
+import type { AvQuestRow } from '../../data/alteracValley.ts';
+
+/** One stack the auto-loot banked. */
+export interface AvDrop {
+  item: number;
+  count: number;
+}
+
+/** A loot row as the shipped bake holds it, narrowed to what a roll needs. */
+export interface AvLootRow {
+  item: number;
+  /** ChanceOrQuestChance — negative rows are quest drops and their magnitude is the percent. */
+  chance: number;
+  min: number;
+  max: number;
+}
+
+/**
+ * The milestones a team's turn-ins reach. Thresholds are BattleGroundAV.cpp's own; what each one
+ * SPAWNS is a product decision, because CMaNGOS logs a TODO at every one of them (:190, :196, :202,
+ * :214, :222, :231, :240, :249). Only waves the DB names a creature for are spawned — the
+ * mine-supply "ground assault" has none, so it pays reputation and announces, and spawns nothing.
+ */
+export type AvMilestone =
+  | 'air-fleet-1' | 'air-fleet-2' | 'air-fleet-3'
+  | 'boss-summon'
+  | 'ground-assault'
+  | 'cavalry';
+
+export interface AvMilestoneEvent {
+  milestone: AvMilestone;
+  team: BgTeam;
+  /** Creature entries the milestone puts on the field, empty when none is sourced. */
+  spawns: readonly number[];
+}
+
+/** Cite: .cpp:188/:194/:200 — 120 soldier, 60 lieutenant, 30 commander turn-ins. */
+export const AV_FLEET_THRESHOLDS = [120, 60, 30] as const;
+/** Cite: .cpp:212 — the crystal/blood counter arms the summon at 200. */
+export const AV_BOSS_SUMMON_AT = 200;
+/** Cite: .cpp:220/:229 — 28 home-mine and 7 enemy-mine turn-ins. */
+export const AV_GROUND_ASSAULT_AT = { home: 28, enemy: 7 } as const;
+/** Cite: .cpp:238/:247 — 25 harnesses and 25 emptied stables. */
+export const AV_CAVALRY_AT = 25;
+
+/**
+ * The beast each side leads home for Empty Stables. Cite: quest 7027 "Locate an Alterac Ram …
+ * use the Stormpike Training Collar when you are near"; 7001 the same for a Frostwolf. The
+ * collar 17689 / muzzle 17626 is the quest's OWN srcItem, so the verb is standing next to the
+ * beast, never a drop — which is why the auto-turn-in pass cannot see this one.
+ */
+export const AV_TAME_BEAST: Readonly<Record<BgTeam, number>> = Object.freeze({
+  alliance: 10990, // Alterac Ram
+  horde: 10981,    // Frostwolf
+});
+
+/**
+ * The wave each milestone puts on the field. Every entry is the creature the quest is named for:
+ * the three wing commanders' own mounts, the two ram/wolf rider units, and the two summoned lords.
+ * Cite: `creature_template` 14946/14947/14948 (Slidore/Ichman/Vipore), 14943/14944/14945
+ * (Guse/Jeztor/Mulverick), 13576/13577 and 13440/13441, 13419 Ivus and 13256 Lokholar.
+ */
+export const AV_WAVES: Readonly<Record<AvMilestone, Readonly<Record<BgTeam, readonly number[]>>>> =
+  Object.freeze({
+    'air-fleet-1': { alliance: [14946], horde: [14943] },
+    'air-fleet-2': { alliance: [14948], horde: [14944] },
+    'air-fleet-3': { alliance: [14947], horde: [14945] },
+    'boss-summon': { alliance: [13419], horde: [13256] },
+    'ground-assault': { alliance: [], horde: [] },
+    cavalry: { alliance: [13577, 13576, 13576, 13576], horde: [13441, 13440, 13440, 13440] },
+  });
+
+/** Counter slot → the wave it arms. Keyed, not built from the slot, so no cast is needed. */
+const FLEET_MILESTONE: Readonly<Record<number, AvMilestone | undefined>> = Object.freeze({
+  1: 'air-fleet-1', 2: 'air-fleet-2', 3: 'air-fleet-3',
+});
+
+export interface AvQuestLedgerOpts {
+  rng: Rng;
+  /** Loot rows for one creature entry. Empty when the creature has no table. */
+  lootOf(entry: number): readonly AvLootRow[];
+  /** reference_loot_template 1 — what an enemy player's corpse carries in AV. */
+  playerLoot(): readonly AvLootRow[];
+  /** A turn-in landed; the caller steps the match counter (av.ts completeQuest). */
+  onTurnIn(questId: number, team: BgTeam): void;
+  /** A milestone was reached — the caller puts its wave on the field. */
+  onMilestone?(e: AvMilestoneEvent): void;
+}
+
+export interface AvQuestLedger {
+  /** Auto-loot a dead creature for the team that killed it. Returns what was banked. */
+  creditKill(entry: number, killer: BgTeam): AvDrop[];
+  /** Auto-loot a dead enemy PLAYER. Cite: battleground_template.PlayerSkinReflootId 1. */
+  creditPlayerKill(killer: BgTeam): AvDrop[];
+  /** Hand in everything this team can, in quest order. Returns the quest ids completed. */
+  turnIn(team: BgTeam): number[];
+  /** One beast led back to the stable master: steps Empty Stables, half of the cavalry gate.
+   *  Returns the quest id, or null when this team has no stables row. */
+  creditTame(team: BgTeam): number | null;
+  held(team: BgTeam): ReadonlyMap<number, number>;
+  /** Milestones already reached, so a caller can render the war state. */
+  milestones(team: BgTeam): readonly AvMilestone[];
+}
+
+/** Quests whose turn-in the ledger can complete on its own — the ones with a required item. */
+function autoTurnInQuests(team: BgTeam): AvQuestRow[] {
+  // 7027 / 7001 "Empty Stables" carry no ReqItem: they are the return half of the ram quest and
+  // are handed in by riding a mount home, which this ledger has no way to observe.
+  return AV_DATA.quests.filter((q) => q.team === team && q.item && q.count);
+}
+
+export function createAvQuestLedger(o: AvQuestLedgerOpts): AvQuestLedger {
+  const bank: Record<BgTeam, Map<number, number>> = { alliance: new Map(), horde: new Map() };
+  const counters: Record<BgTeam, number[]> = {
+    alliance: new Array<number>(9).fill(0),
+    horde: new Array<number>(9).fill(0),
+  };
+  const reached: Record<BgTeam, Set<AvMilestone>> = { alliance: new Set(), horde: new Set() };
+  const questsFor = { alliance: autoTurnInQuests('alliance'), horde: autoTurnInQuests('horde') };
+  /** Item ids any AV quest asks for — nothing else is worth banking. */
+  const wanted = new Set(AV_DATA.quests.map((q) => q.item).filter((i): i is number => !!i));
+
+  function roll(rows: readonly AvLootRow[], team: BgTeam): AvDrop[] {
+    const out: AvDrop[] = [];
+    for (const r of rows) {
+      if (!wanted.has(r.item)) continue;
+      // A quest row is stored negative and drops for anyone who can use it; a plain row rolls.
+      const pct = Math.abs(r.chance);
+      if (pct < 100 && o.rng.next() * 100 >= pct) continue;
+      const lo = Math.max(1, r.min | 0);
+      const hi = Math.max(lo, r.max | 0);
+      const count = lo === hi ? lo : lo + o.rng.int(0, hi - lo);
+      out.push({ item: r.item, count });
+      bank[team].set(r.item, (bank[team].get(r.item) ?? 0) + count);
+    }
+    return out;
+  }
+
+  function fire(team: BgTeam, m: AvMilestone): void {
+    if (reached[team].has(m)) return;
+    reached[team].add(m);
+    o.onMilestone?.({ milestone: m, team, spawns: AV_WAVES[m][team] });
+  }
+
+  /** The counter thresholds, read after a turn-in stepped `slot`. */
+  function checkMilestones(team: BgTeam, slot: number): void {
+    const c = counters[team];
+    const fleet = FLEET_MILESTONE[slot];
+    if (fleet && c[slot]! >= AV_FLEET_THRESHOLDS[slot - 1]!) fire(team, fleet);
+    if (slot === 4 && c[4]! >= AV_BOSS_SUMMON_AT) fire(team, 'boss-summon');
+    if ((slot === 5 || slot === 6)
+      && c[5]! >= AV_GROUND_ASSAULT_AT.home && c[6]! >= AV_GROUND_ASSAULT_AT.enemy) {
+      fire(team, 'ground-assault');
+    }
+    if ((slot === 7 || slot === 8) && c[7]! >= AV_CAVALRY_AT && c[8]! >= AV_CAVALRY_AT) {
+      fire(team, 'cavalry');
+    }
+  }
+
+  return {
+    creditKill(entry, killer) {
+      return roll(o.lootOf(entry), killer);
+    },
+
+    creditPlayerKill(killer) {
+      return roll(o.playerLoot(), killer);
+    },
+
+    turnIn(team) {
+      const done: number[] = [];
+      const held = bank[team];
+      // A pass per quest, repeated while anything still fits: 60 scraps is three turn-ins.
+      let moved = true;
+      while (moved) {
+        moved = false;
+        for (const q of questsFor[team]) {
+          const have = held.get(q.item!) ?? 0;
+          if (have < q.count!) continue;
+          held.set(q.item!, have - q.count!);
+          counters[team][q.slot] = (counters[team][q.slot] ?? 0) + q.step;
+          o.onTurnIn(q.id, team);
+          checkMilestones(team, q.slot);
+          done.push(q.id);
+          moved = true;
+        }
+      }
+      return done;
+    },
+
+    creditTame(team) {
+      const q = AV_DATA.quests.find((r) => r.team === team && r.counter === 'empty-stables');
+      if (!q) return null;
+      counters[team][q.slot] = (counters[team][q.slot] ?? 0) + (q.step || 1);
+      o.onTurnIn(q.id, team);
+      checkMilestones(team, q.slot);
+      return q.id;
+    },
+
+    held: (team) => bank[team],
+    milestones: (team) => [...reached[team]],
+  };
+}

package/src/domain/bg/avSession.ts

@@ -0,0 +1,196 @@
+// Streams an AV creature into the one endless session when a player seat comes near, and hands the
+// seat back when the fight leaves — both halves, as liveAggroStream.ts:545-612 does for the floor.
+
+import type { BgTeam, BgUnit, BgUnitId } from './types.ts';
+import type { BgWorld } from './bgWorld.ts';
+import type { AvField } from './avField.ts';
+import type { CombatantSpec } from '../../engine/combat.ts';
+import { COMBAT_DROP_YD } from '../../engine/combat/creatureLeash.ts';
+import { STOREY_DZ_YD } from '../nav/storey.ts';
+
+/** How close an NPC gets to a player seat before it becomes a combat body. */
+export const AV_SEAT_YD = 55;
+/** Seat handed back at this range. Wider than AV_SEAT_YD by the floor's own margin (48 -> 64), so a
+ *  body on the band edge is not streamed in and dropped on the same sync. */
+export const AV_UNSEAT_YD = 73;
+/** Seats an AV match hands to NPCs, live at once. The ally figure leaves room under MAX_ALLIES (78)
+ *  for the 39 player seats and their pets. */
+export const AV_MAX_NPC_ALLIES = 24;
+export const AV_MAX_NPC_ENEMIES = 40;
+
+/** Only the part of CombatSession this bridge touches — domain does not depend on the whole API. */
+export interface AvCombatSession {
+  injectEnemy(spec: CombatantSpec, position?: { x: number; y: number; z?: number }): string | null;
+  injectAlly?(spec: CombatantSpec, position?: { x: number; y: number; z?: number }): string | null;
+  setUnitPosYd(side: string, pos: { x: number; y: number; z?: number }): void;
+  unitPosYd?(side: string): { x: number; y: number; z?: number } | null | undefined;
+  viewOfSide?(side: string): { hp: number; maxHp: number; engaged?: boolean } | null;
+  disengageEnemySides?(sides: readonly string[]): number;
+  disengageAllySides?(sides: readonly string[]): number;
+}
+
+export interface AvSessionOpts {
+  world: BgWorld;
+  field: AvField;
+  session: AvCombatSession;
+  /** The side the PLAYER is on — an NPC of this team is injected as an ally, else as an enemy. */
+  playerTeam: BgTeam;
+  /** CombatantSpec for a creature entry; null leaves the body world-only. */
+  specOf(entry: number): CombatantSpec | null;
+  /** Called once per injected body, so the screen can keep its own side ↔ unit maps. */
+  onSeated?(unit: BgUnit, side: string): void;
+  /** The seat this body held is being handed back — the screen drops its own side ↔ unit maps. */
+  onReleased?(unit: BgUnit, side: string): void;
+  /** An injected NPC just died in the session — the caller banks the AV kill. */
+  onKilled?(unit: BgUnit, entry: number, by: BgTeam): void;
+  seatYd?: number;
+  unseatYd?: number;
+}
+
+export interface AvSessionBridge {
+  /** Seat what is in reach, mirror what is seated, release what the fight left. */
+  sync(): void;
+  /** side ↔ npc unit id, for the caller's chip/feed lookups. */
+  sideOf(unitId: BgUnitId): string | undefined;
+  seatedCount(): { allies: number; enemies: number };
+}
+
+export function createAvSessionBridge(o: AvSessionOpts): AvSessionBridge {
+  const { world, field, session } = o;
+  const seatYd = o.seatYd ?? AV_SEAT_YD;
+  const unseatYd = Math.max(o.unseatYd ?? AV_UNSEAT_YD, seatYd + 1);
+  const sideByNpc = new Map<BgUnitId, string>();
+  const npcBySide = new Map<string, BgUnitId>();
+  /** Seats held RIGHT NOW. Counting lifetime injects instead is what made the field go inert. */
+  let allies = 0;
+  let enemies = 0;
+
+  /** Player seats — every unit that is NOT an NPC. Both teams: an enemy bot pulls guards too. */
+  function seats(): BgUnit[] {
+    const out: BgUnit[] = [];
+    for (const u of world.units.values()) {
+      if (u.npc || !world.alive(u)) continue;
+      out.push(u);
+    }
+    return out;
+  }
+
+  /** Nearest player seat ON THE SAME STOREY. Irondeep Mine sits 28-49 yd under the Alliance start,
+   *  so a planar band gave all 40 enemy seats to troggs in a cave and the match never left the gate. */
+  function nearestSeatDist(u: BgUnit, near: readonly BgUnit[]): number {
+    let best = Infinity;
+    for (const s of near) {
+      if (Math.abs((s.z ?? 0) - (u.z ?? 0)) > STOREY_DZ_YD) continue;
+      const dx = s.pos.x - u.pos.x;
+      const dy = s.pos.y - u.pos.y;
+      const d2 = dx * dx + dy * dy;
+      if (d2 < best) best = d2;
+    }
+    return best === Infinity ? Infinity : Math.sqrt(best);
+  }
+
+  function seat(unit: BgUnit): void {
+    const spec = o.specOf(unit.npc!.entry);
+    if (!spec) return;
+    const pos = { x: unit.pos.x, y: unit.pos.y, z: unit.z };
+    let side: string | null = null;
+    // A neutral body is hostile to everyone, so it only ever takes an ENEMY seat. Seating it as an
+    // ally put half the valley's wildlife — boars, wolves, dreadmaws — inside the player's raid.
+    if (unit.team === o.playerTeam && !unit.npc?.neutral) {
+      if (allies >= AV_MAX_NPC_ALLIES || !session.injectAlly) return;
+      side = session.injectAlly(spec, pos);
+      if (side) allies++;
+    } else {
+      if (enemies >= AV_MAX_NPC_ENEMIES) return;
+      side = session.injectEnemy(spec, pos);
+      if (side) enemies++;
+    }
+    if (!side) return;
+    // A seat the session recycled off a corpse still carries the dead body's mapping. Drop that
+    // first, or two npc ids answer to one side and the corpse keeps writing over the new occupant.
+    const previous = npcBySide.get(side);
+    if (previous != null && previous !== unit.id) sideByNpc.delete(previous);
+    sideByNpc.set(unit.id, side);
+    npcBySide.set(side, unit.id);
+    o.onSeated?.(unit, side);
+  }
+
+  /** Give the seat back. `dropOnly` is a body the session already took off the board (a corpse). */
+  function release(id: BgUnitId, side: string, dropOnly: boolean): void {
+    sideByNpc.delete(id);
+    npcBySide.delete(side);
+    const u = world.units.get(id);
+    const wasAlly = u ? (u.team === o.playerTeam && !u.npc?.neutral) : side.startsWith('ally');
+    if (wasAlly) allies = Math.max(0, allies - 1);
+    else enemies = Math.max(0, enemies - 1);
+    if (!dropOnly) {
+      if (wasAlly) session.disengageAllySides?.([side]);
+      else session.disengageEnemySides?.([side]);
+      // De-streaming a LIVING body is an evade, and an evade heals: the same reset
+      // releaseEnemyToPassive does, so the chip and the next inject agree. Cite: EnterEvadeMode.
+      if (u) u.hp = u.maxHp;
+    }
+    if (u) o.onReleased?.(u, side);
+  }
+
+  return {
+    sync() {
+      if (world.ended || !world.gatesOpen) return;
+      const near = seats();
+
+      // 1. release what the fight left, FIRST, so the freed seats are available this same sync. An
+      //    engaged body keeps its seat out to COMBAT_DROP_YD. Cite: liveAggroStream.ts:571-605.
+      for (const [id, side] of [...sideByNpc]) {
+        const u = world.units.get(id);
+        if (!u) { release(id, side, true); continue; }
+        if (!world.alive(u)) continue; // the mirror below owns the death, and it drops the seat
+        const v = session.viewOfSide?.(side);
+        const engaged = !!v && v.hp > 0 && v.hp < v.maxHp;
+        if (nearestSeatDist(u, near) > (engaged ? COMBAT_DROP_YD : unseatYd)) release(id, side, false);
+      }
+
+      // 2. seat what the fight has reached
+      for (const u of field.npcs()) {
+        if (!world.alive(u) || sideByNpc.has(u.id)) continue;
+        if (nearestSeatDist(u, near) <= seatYd) seat(u);
+      }
+
+      // 3. mirror the seated bodies: world position in, session health out
+      for (const [id, side] of [...sideByNpc]) {
+        const u = world.units.get(id);
+        if (!u) { release(id, side, true); continue; }
+        // Chase on top of wander: session owns while engaged; world wander owns OOC.
+        // Cite: MotionMaster.cpp:615 Interrupt + :130 top()->Update.
+        const v = session.viewOfSide?.(side);
+        if (world.alive(u)) {
+          if (v?.engaged === true) {
+            const at = session.unitPosYd?.(side);
+            if (at) {
+              u.pos = { x: at.x, y: at.y };
+              world.settleZ(u);
+            }
+          } else {
+            session.setUnitPosYd(side, { x: u.pos.x, y: u.pos.y, z: u.z });
+          }
+        }
+        if (!v || v.maxHp <= 0) continue;
+        u.hp = Math.max(0, Math.min(u.maxHp, Math.round((v.hp / v.maxHp) * u.maxHp)));
+        if (u.hp > 0 || u.deadUntilMs != null) continue;
+        // The killer is whoever it was fighting: an NPC only ever dies to the other side. A
+        // NEUTRAL body has no side to be opposite of — it only ever takes an enemy seat here, so
+        // the kill is the player team's, not the team `neutralSideFor` parked its body on.
+        const by: BgTeam = u.npc!.neutral
+          ? o.playerTeam
+          : (u.team === 'alliance' ? 'horde' : 'alliance');
+        // A battleground creature does not respawn on the 30 s cycle - its node event does it.
+        world.kill(u, Number.MAX_SAFE_INTEGER);
+        o.onKilled?.(u, u.npc!.entry, by);
+        // The corpse is the session's to recycle; the bridge stops holding the seat for it.
+        release(id, side, true);
+      }
+    },
+
+    sideOf: (unitId) => sideByNpc.get(unitId),
+    seatedCount: () => ({ allies, enemies }),
+  };
+}