feat(inventory): port retail weapon switching

Sequence primary weapon replacement through the server-confirmed AutoWield transaction: return the occupied weapon to the player pack, wait for its move event, then wield the requested item. Route authoritative CombatMode property updates so peace stays peace and war adopts the new weapon stance without client-synthesized animation.

Co-Authored-By: Codex <codex@openai.com>

docs/research/2026-07-12-retail-weapon-switch-pseudocode.md

@@ -0,0 +1,108 @@
+# Retail inventory weapon-switch pseudocode
+
+## Scope
+
+Inventory double-click of a weapon while another primary weapon is equipped,
+in both peace and combat modes. The UI request sequence is shared; combat-mode
+animation remains server-authoritative.
+
+## Retail oracle
+
+- `ItemHolder::DetermineUseResult @ 0x00588460` classifies an owned combat-use
+  item as `WieldRight`.
+- `CPlayerSystem::UsingItem @ 0x00562F70` dispatches that result to
+  `AutoWield(item, SLOT_SIDE_RIGHT, 0, 1, 0, 1)`.
+- `CPlayerSystem::AutoWield @ 0x00560A60` treats
+  `0x03500000` (`MeleeWeapon | MissileWeapon | Held | TwoHanded`) as one
+  weapon-ready group. If occupied, it records the requested item, sends the
+  blocking weapon to the player container, and does not wield the requested
+  item yet.
+- `CPlayerSystem::RecvNotice_ServerSaysMoveItem @ 0x00563260` retries
+  `AutoWield` only after the server confirms the blocking item moved.
+- `ACCWeenieObject::UIAttemptWield @ 0x0058D590` sends
+  `GetAndWieldItem(item, equipMask)`.
+- `ClientCombatSystem::OnQualityChanged @ 0x0056C1B0` reads player
+  PropertyInt 40 (`CombatMode`) and applies it through `SetCombatMode`.
+
+Addresses are from `docs/research/named-retail/symbols.json`; pseudo-C is in
+`docs/research/named-retail/acclient_2013_pseudo_c.txt`.
+
+## Cross-reference
+
+- ACE `Player_Inventory.cs` says the client normally sends the conflicting
+  item's dequip before `GetAndWieldItem`. `TryShuffleStance` changes a player
+  who is already in combat to Missile, Magic, or Melee after the new item is
+  equipped; it leaves a player in peace mode in peace.
+- ACE `Creature_Combat.cs::SwitchCombatStyles` performs the visible
+  old-stance -> peace -> new-stance motion chain and sends
+  `PrivateUpdatePropertyInt(CombatMode, ...)`.
+- holtburger independently confirms the action/event shapes:
+  `GetAndWieldItem { item_guid, equip_mask }`, `WieldObject`, and
+  PropertyInt 40 as `CombatMode`.
+
+## Faithful pseudocode
+
+```text
+on inventory item double-click(item):
+    decision = DetermineUseResult(item)
+    if decision is WieldRight or WieldLeft or AutoSort:
+        auto_wield(item)
+
+auto_wield(item):
+    if another auto-wield transaction is waiting for the server:
+        consume the request without sending another inventory action
+
+    if item has no valid equip location or is already equipped:
+        return false
+
+    if item.validLocations intersects WEAPON_READY_MASK:
+        desiredMask = item.validLocations & WEAPON_READY_MASK
+        blocker = player's equipped item intersecting WEAPON_READY_MASK
+
+        if blocker exists:
+            pending = (requestedItem = item.id, blockingItem = blocker.id)
+            send PutItemInContainer(blocker.id, player.id, placement = 0)
+            return true
+
+        send_wield(item, desiredMask)
+        return true
+
+    use the existing retail slot/auto-wear selection rules
+    send_wield(item, selectedMask)
+
+on server-confirmed item move(blocker):
+    if blocker matches pending.blockingItem
+       and blocker is now loose in the player's main pack:
+        requested = pending.requestedItem
+        clear pending before re-entry
+        auto_wield(requested)
+
+on server inventory-request failure(item, error):
+    if item matches pending.blockingItem or pending.requestedItem:
+        clear pending
+
+send_wield(item, mask):
+    update the retained inventory/paperdoll projection optimistically
+    send GetAndWieldItem(item.id, mask)
+
+on PrivateUpdatePropertyInt(property = CombatMode, value):
+    if value is exactly NonCombat, Melee, Missile, or Magic:
+        CombatState.SetCombatMode(value)
+```
+
+## Animation ownership
+
+The client must not synthesize a local bow-to-sword animation. In peace mode,
+ACE leaves `CombatMode` as `NonCombat`. In combat mode, ACE selects the new
+weapon's stance and sends the authoritative motion stream plus PropertyInt 40.
+The inventory controller only sequences the two wire requests and waits for
+the old weapon's confirmed move; the existing motion and equipped-child
+render paths consume the server events.
+
+## Known remaining retail surface
+
+This port covers the primary weapon-ready group requested here. Retail
+`AutoWield` also has extra blocker logic for incompatible shields and missile
+ammo, plus its full `AutoWieldIsLegal` requirement checks. Those pre-existing
+paperdoll/auto-wield gaps remain tracked by divergence row AP-108 rather than
+being guessed from incomplete item properties.