feat(game): introduce GameHandler domain interfaces and eliminate friend declarations

Add game_interfaces.hpp with five narrow domain contracts that GameHandler now
publishes to its domain handlers, replacing the previous friend-class anti-pattern.

Changes:
- include/game/game_interfaces.hpp (new): IConnectionState, ITargetingState,
  IEntityAccess, ISocialState, IPvpState — each interface exposes only the state
  its consumer legitimately needs
- include/game/game_handler.hpp: GameHandler inherits all five interfaces;
  include of game_interfaces.hpp added
- include/game/movement_handler.hpp: remove `friend class GameHandler`; add
  public named accessors for previously-private fields (monsterMovePacketsThisTickRef,
  timeSinceLastMoveHeartbeatRef, resetMovementClock, setFalling, setFallStartMs)
- include/game/spell_handler.hpp: remove `friend class GameHandler/InventoryHandler/
  CombatHandler/EntityController`; promote private packet handlers (handlePetSpells,
  handleListStabledPets, pet stable commands, DBC loaders) to public; add accessor
  methods for aura cache, known spells, and player aura slot mutation
- src/game/game_handler.cpp, game_handler_callbacks.cpp, game_handler_packets.cpp:
  replace direct private field access with the new accessor API
  (e.g. casting_ → isCasting(), monsterMovePacketsThisTick_ → ...ThisTickRef())
- src/game/inventory_handler.cpp, combat_handler.cpp, entity_controller.cpp:
  replace friend-class private access with public accessor calls

No behaviour change. All 13 test suites pass. Zero build warnings.

include/game/game_handler.hpp

@@ -1,5 +1,6 @@
 #pragma once
 
+#include "game/game_interfaces.hpp"
 #include "game/world_packets.hpp"
 #include "game/character.hpp"
 #include "game/opcode_table.hpp"
@@ -125,7 +126,11 @@ using WorldConnectFailureCallback = std::function<void(const std::string& reason
  * - World entry
  * - Game packets
  */
-class GameHandler {
+class GameHandler : public IConnectionState,
+                     public ITargetingState,
+                     public IEntityAccess,
+                     public ISocialState,
+                     public IPvpState {
 public:
     // Talent data structures (aliased from handler_types.hpp)
     using TalentEntry = game::TalentEntry;

include/game/game_interfaces.hpp

@@ -0,0 +1,126 @@
+#pragma once
+
+// Domain interfaces for GameHandler decomposition (Phase 1.2A).
+// Each interface defines a narrow contract for a specific domain concern,
+// enabling domain handlers to depend only on the state they need.
+
+#include <cstdint>
+#include <memory>
+#include <string>
+#include <vector>
+#include <array>
+#include <unordered_map>
+
+namespace wowee::network { class WorldSocket; }
+
+namespace wowee::game {
+
+// Forward declarations
+class Entity;
+class EntityManager;
+enum class WorldState;
+struct ContactEntry;
+struct BgQueueSlot;
+struct AvailableBgInfo;
+struct BgScoreboardData;
+struct BgPlayerPosition;
+struct ArenaTeamStats;
+struct ArenaTeamRoster;
+struct GuildRosterData;
+struct GuildInfoData;
+struct GuildQueryResponseData;
+struct CreatureQueryResponseData;
+struct GameObjectQueryResponseData;
+
+// ---------------------------------------------------------------------------
+// IConnectionState — server connection and authentication state
+// ---------------------------------------------------------------------------
+class IConnectionState {
+public:
+    virtual ~IConnectionState() = default;
+
+    virtual bool isConnected() const = 0;
+    virtual bool isInWorld() const = 0;
+    virtual WorldState getState() const = 0;
+    virtual network::WorldSocket* getSocket() = 0;
+    virtual const std::vector<uint8_t>& getSessionKey() const = 0;
+};
+
+// ---------------------------------------------------------------------------
+// ITargetingState — target, focus, and mouseover management
+// ---------------------------------------------------------------------------
+class ITargetingState {
+public:
+    virtual ~ITargetingState() = default;
+
+    virtual void setTarget(uint64_t guid) = 0;
+    virtual void clearTarget() = 0;
+    virtual uint64_t getTargetGuid() const = 0;
+    virtual std::shared_ptr<Entity> getTarget() const = 0;
+    virtual bool hasTarget() const = 0;
+
+    virtual void setFocus(uint64_t guid) = 0;
+    virtual void clearFocus() = 0;
+    virtual uint64_t getFocusGuid() const = 0;
+    virtual bool hasFocus() const = 0;
+
+    virtual void setMouseoverGuid(uint64_t guid) = 0;
+    virtual uint64_t getMouseoverGuid() const = 0;
+};
+
+// ---------------------------------------------------------------------------
+// IEntityAccess — entity queries and name/info caching
+// ---------------------------------------------------------------------------
+class IEntityAccess {
+public:
+    virtual ~IEntityAccess() = default;
+
+    virtual EntityManager& getEntityManager() = 0;
+    virtual const EntityManager& getEntityManager() const = 0;
+
+    virtual void queryPlayerName(uint64_t guid) = 0;
+    virtual void queryCreatureInfo(uint32_t entry, uint64_t guid) = 0;
+    virtual std::string getCachedPlayerName(uint64_t guid) const = 0;
+    virtual std::string getCachedCreatureName(uint32_t entry) const = 0;
+    virtual const std::unordered_map<uint64_t, std::string>& getPlayerNameCache() const = 0;
+    virtual const std::unordered_map<uint32_t, CreatureQueryResponseData>& getCreatureInfoCache() const = 0;
+    virtual const GameObjectQueryResponseData* getCachedGameObjectInfo(uint32_t entry) const = 0;
+};
+
+// ---------------------------------------------------------------------------
+// ISocialState — friends, ignore list, contacts, guild info
+// ---------------------------------------------------------------------------
+class ISocialState {
+public:
+    virtual ~ISocialState() = default;
+
+    virtual void addFriend(const std::string& playerName, const std::string& note = "") = 0;
+    virtual void removeFriend(const std::string& playerName) = 0;
+    virtual void addIgnore(const std::string& playerName) = 0;
+    virtual void removeIgnore(const std::string& playerName) = 0;
+    virtual const std::unordered_map<std::string, uint64_t>& getIgnoreCache() const = 0;
+    virtual const std::vector<ContactEntry>& getContacts() const = 0;
+
+    virtual bool isInGuild() const = 0;
+    virtual const std::string& getGuildName() const = 0;
+    virtual const GuildRosterData& getGuildRoster() const = 0;
+    virtual bool hasGuildRoster() const = 0;
+};
+
+// ---------------------------------------------------------------------------
+// IPvpState — battleground queues, arena teams, scoreboard
+// ---------------------------------------------------------------------------
+class IPvpState {
+public:
+    virtual ~IPvpState() = default;
+
+    virtual bool hasPendingBgInvite() const = 0;
+    virtual void acceptBattlefield(uint32_t queueSlot = 0xFFFFFFFF) = 0;
+    virtual void declineBattlefield(uint32_t queueSlot = 0xFFFFFFFF) = 0;
+    virtual const std::array<BgQueueSlot, 3>& getBgQueues() const = 0;
+    virtual const std::vector<AvailableBgInfo>& getAvailableBgs() const = 0;
+    virtual const BgScoreboardData* getBgScoreboard() const = 0;
+    virtual const std::vector<ArenaTeamStats>& getArenaTeamStats() const = 0;
+};
+
+} // namespace wowee::game

include/game/movement_handler.hpp

@@ -148,6 +148,11 @@ public:
     uint32_t& monsterMovePacketsThisTickRef() { return monsterMovePacketsThisTick_; }
     uint32_t& monsterMovePacketsDroppedThisTickRef() { return monsterMovePacketsDroppedThisTick_; }
 
+    // Movement clock / fall state setters (formerly accessed via friend)
+    void resetMovementClock() { movementClockStart_ = std::chrono::steady_clock::now(); lastMovementTimestampMs_ = 0; }
+    void setFalling(bool falling) { isFalling_ = falling; }
+    void setFallStartMs(uint32_t ms) { fallStartMs_ = ms; }
+
     // Taxi state references for GameHandler update/processing
     bool& onTaxiFlightRef() { return onTaxiFlight_; }
     bool& taxiMountActiveRef() { return taxiMountActive_; }
@@ -197,8 +202,6 @@ private:
     void buildTaxiCostMap();
     void startClientTaxiPath(const std::vector<uint32_t>& pathNodes);
 
-    friend class GameHandler;
-
     GameHandler& owner_;
 
     // --- Movement state ---

include/game/spell_handler.hpp

@@ -80,6 +80,23 @@ public:
         return (it != unitCastStates_.end() && it->second.casting) ? &it->second : nullptr;
     }
     void clearUnitCastStates() { unitCastStates_.clear(); }
+    void removeUnitCastState(uint64_t guid) { unitCastStates_.erase(guid); }
+
+    // Aura cache mutation (formerly accessed via friend)
+    void clearUnitAurasCache() { unitAurasCache_.clear(); }
+    void removeUnitAuraCache(uint64_t guid) { unitAurasCache_.erase(guid); }
+
+    // Known spells mutation (formerly accessed via friend)
+    void addKnownSpell(uint32_t spellId) { knownSpells_.insert(spellId); }
+    bool hasKnownSpell(uint32_t spellId) const { return knownSpells_.count(spellId) > 0; }
+
+    // Target aura mutation (formerly accessed via friend)
+    void clearTargetAuras() { for (auto& slot : targetAuras_) slot = AuraSlot{}; }
+
+    // Player aura mutation (formerly accessed via friend)
+    void resetPlayerAuras(size_t capacity) { playerAuras_.clear(); playerAuras_.resize(capacity); }
+    AuraSlot& getPlayerAuraSlotRef(size_t slot) { return playerAuras_[slot]; }
+    std::vector<AuraSlot>& getPlayerAurasMut() { return playerAuras_; }
 
     // Target cast helpers
     bool isTargetCasting() const;
@@ -204,6 +221,20 @@ public:
     // Update per-frame timers (call from GameHandler::update)
     void updateTimers(float dt);
 
+    // Packet handlers dispatched from GameHandler's opcode table
+    void handlePetSpells(network::Packet& packet);
+    void handleListStabledPets(network::Packet& packet);
+
+    // Pet stable commands (called via GameHandler delegation)
+    void requestStabledPetList();
+    void stablePet(uint8_t slot);
+    void unstablePet(uint32_t petNumber);
+
+    // DBC cache loading (called from GameHandler during login)
+    void loadSpellNameCache() const;
+    void loadSkillLineAbilityDbc();
+    void categorizeTrainerSpells();
+
 private:
     // --- Packet handlers ---
     void handleInitialSpells(network::Packet& packet);
@@ -214,13 +245,6 @@ private:
     void handleCooldownEvent(network::Packet& packet);
     void handleAuraUpdate(network::Packet& packet, bool isAll);
     void handleLearnedSpell(network::Packet& packet);
-    void handlePetSpells(network::Packet& packet);
-    void handleListStabledPets(network::Packet& packet);
-
-    // Pet stable
-    void requestStabledPetList();
-    void stablePet(uint8_t slot);
-    void unstablePet(uint32_t petNumber);
 
     void handleCastResult(network::Packet& packet);
     void handleSpellFailedOther(network::Packet& packet);
@@ -252,20 +276,12 @@ private:
     // Find the on-use spell for an item (trigger=0 Use or trigger=5 NoDelay).
     // CMSG_USE_ITEM requires a valid spellId or the server silently ignores it.
     uint32_t findOnUseSpellId(uint32_t itemId) const;
-    void loadSpellNameCache() const;
-    void loadSkillLineAbilityDbc();
-    void categorizeTrainerSpells();
     void handleSupercededSpell(network::Packet& packet);
     void handleRemovedSpell(network::Packet& packet);
     void handleUnlearnSpells(network::Packet& packet);
     void handleTalentsInfo(network::Packet& packet);
     void handleAchievementEarned(network::Packet& packet);
 
-    friend class GameHandler;
-    friend class InventoryHandler;
-    friend class CombatHandler;
-    friend class EntityController;
-
     GameHandler& owner_;
 
     // --- Spell state ---