PR cleanup

Sunrise/Sunrise.vcxproj

@@ -138,6 +138,11 @@
     <ClCompile Include="src\state\runtime\state_account_runtime.cpp" />
     <ClCompile Include="src\state\runtime\state_account_acquisition_runtime.cpp" />
     <ClCompile Include="src\state\runtime\state_account_dismantle_runtime.cpp" />
+    <ClCompile Include="src\state\runtime\state_account_dismantle_staging.cpp" />
+    <ClCompile Include="src\state\runtime\state_account_equipment_runtime.cpp" />
+    <ClCompile Include="src\state\runtime\state_account_identity_runtime.cpp" />
+    <ClCompile Include="src\state\runtime\state_account_profile_runtime.cpp" />
+    <ClCompile Include="src\state\runtime\state_account_socket_runtime.cpp" />
     <ClCompile Include="src\state\runtime\state_account_item_action_runtime.cpp" />
     <ClCompile Include="src\core\ui\busy\ui_busy_overlay.cpp" />
     <ClCompile Include="src\core\ui\busy\ui_busy_state.cpp" />

Sunrise/src/client/graphics/wine_compat.cpp

@@ -1,14 +1,15 @@
 #include "wine_compat.h"
 
-#include "windows.h"
+#include <Windows.h>
 
 namespace sunrise::client::graphics {
 
-// Helper function to let wine know that we will be using the display
-void initialize_wine_display() {
-    HDC hdc = GetDC(NULL);
-    if (hdc) {
-        ReleaseDC(NULL, hdc);
+/** Opens and releases the screen device context, which is what makes Wine attach its display. */
+void initialize_wine_display() noexcept {
+    const HDC screen = GetDC(nullptr);
+    if (screen != nullptr) {
+        (void)ReleaseDC(nullptr, screen);
     }
 }
+
 } // namespace sunrise::client::graphics

Sunrise/src/client/graphics/wine_compat.h

@@ -1,5 +1,12 @@
 #pragma once
 
 namespace sunrise::client::graphics {
-void initialize_wine_display();
-}
+
+/**
+ * Opens and releases the screen device context once, which is what makes Wine attach its display.
+ * Wine defers that attach until something asks for the display, and the renderer expects it to
+ * have happened already. On Windows the call is harmless.
+ */
+void initialize_wine_display() noexcept;
+
+} // namespace sunrise::client::graphics

Sunrise/src/client/hooks/egress/lifecycle/egress_guard_exports.cpp

@@ -1,10 +1,10 @@
-#include <string>
+#include <string_view>
 
+#include "../../../../core/runtime/host_environment.h"
 #include "../dns/egress_dns_replacements.h"
 #include "../extensions/egress_extension_replacements.h"
 #include "../resolver/replacements.h"
 #include "../winsock/replacements.h"
-#include "core/runtime/host_environment.h"
 #include "internal.h"
 
 namespace sunrise::client::hooks::egress::lifecycle {
@@ -22,29 +22,39 @@ export_definition(ModuleSlot module, const char* name, Function replacement) noe
     return ExportDefinition{module, name, reinterpret_cast<void*>(replacement)};
 }
 
-} // namespace
+/** Winsock's own generic failure code, which a refused connection call answers with. */
+constexpr int kSocketError = -1;
+/** WSAHOST_NOT_FOUND. A refused name lookup answers with it, so nothing resolves an address. */
+constexpr int kHostNotFound = 11001;
 
-// Dummy functions, these are not exported by wine so we provide at least 5 bytes for detours to
-// copy
-__declspec(noinline) int WSAAPI Dummy_WSAConnectByList() {
-    volatile int dummy = 0;
-    dummy += 1;
-    return -1; // SOCKET_ERROR
+/**
+ * Stands in for one export Wine does not provide, so the guard still owns the call.
+ * Detours copies at least five bytes from a target, so the body must not fold away to a bare
+ * return. The volatile store is what keeps it long enough to detour.
+ * @return The refusal the real export would answer with.
+ */
+__declspec(noinline) int WSAAPI absent_connect_by_list() noexcept {
+    volatile int occupied = 0;
+    occupied += 1;
+    return kSocketError;
 }
 
-__declspec(noinline) int WSAAPI Dummy_GetAddrInfoExA() {
-    volatile int dummy = 0;
-    dummy += 1;
-    return 11001; // WSAHOST_NOT_FOUND
+/** @return The refusal the real export would answer with. See absent_connect_by_list. */
+__declspec(noinline) int WSAAPI absent_address_info_ex_a() noexcept {
+    volatile int occupied = 0;
+    occupied += 1;
+    return kHostNotFound;
 }
 
+} // namespace
+
 /** Finds the whole Windows SDK egress surface for one atomic Detours batch. */
 bool resolve_specs(std::span<hooking::detour::Spec, kHookCount> specs,
                    std::span<const char*, kHookCount> names,
                    std::span<bool, kHookCount> resolved,
                    std::size_t& count) noexcept {
     count = 0;
-    const bool is_wine = sunrise::core::runtime::is_wine();
+    const bool underWine = core::runtime::is_wine();
 
     const std::array<ExportDefinition, kHookCount> exports{
         export_definition(ModuleSlot::winsock, "connect", &winsock::connection::connect_socket),
@@ -93,12 +103,14 @@ bool resolve_specs(std::span<hooking::detour::Spec, kHookCount> specs,
         void* target = reinterpret_cast<void*>(GetProcAddress(module, definition.name));
         names[index] = definition.name;
 
-        if (target == nullptr && is_wine) {
-            const std::string_view funcName(definition.name);
-            if (funcName == "WSAConnectByList") {
-                target = reinterpret_cast<void*>(&Dummy_WSAConnectByList);
-            } else if (funcName == "GetAddrInfoExA") {
-                target = reinterpret_cast<void*>(&Dummy_GetAddrInfoExA);
+        // Wine does not export every name Windows does. A missing one still needs a target, or
+        // the guard would leave that call unowned.
+        if (target == nullptr && underWine) {
+            const std::string_view exportName(definition.name);
+            if (exportName == "WSAConnectByList") {
+                target = reinterpret_cast<void*>(&absent_connect_by_list);
+            } else if (exportName == "GetAddrInfoExA") {
+                target = reinterpret_cast<void*>(&absent_address_info_ex_a);
             }
         }
 

Sunrise/src/core/runtime/host_environment.cpp

@@ -1,18 +1,18 @@
 #include "host_environment.h"
 
-#include "windows.h"
+#include <Windows.h>
 
 namespace sunrise::core::runtime {
-bool is_wine() {
-    static const bool is_linux = []() -> bool {
-        HMODULE hntdll = GetModuleHandleW(L"ntdll.dll");
-        if (!hntdll) {
-            return false;
-        }
-        return GetProcAddress(hntdll, "wine_get_version")
-               != nullptr; // Exported by wine to identify itself but not by real windows
-    }();
 
-    return is_linux;
+/** @return True when the loaded ntdll exports Wine's own version entry point. */
+bool is_wine() noexcept {
+    // Wine exports this from ntdll to name itself and Windows never does. The host cannot change
+    // while the process lives, so the answer is resolved once.
+    static const bool underWine = [] {
+        const HMODULE ntdll = GetModuleHandleW(L"ntdll.dll");
+        return ntdll != nullptr && GetProcAddress(ntdll, "wine_get_version") != nullptr;
+    }();
+    return underWine;
 }
+
 } // namespace sunrise::core::runtime

Sunrise/src/core/runtime/host_environment.h

@@ -1,5 +1,11 @@
 #pragma once
 
 namespace sunrise::core::runtime {
-bool is_wine();
-}
+
+/**
+ * Reports whether the process runs under Wine instead of Windows.
+ * @return True when the loaded ntdll exports Wine's own version entry point.
+ */
+[[nodiscard]] bool is_wine() noexcept;
+
+} // namespace sunrise::core::runtime

Sunrise/src/state/runtime/state_account_dismantle_staging.cpp

@@ -0,0 +1,463 @@
+/** Dismantle staging: the payout it credits and the after-image it is committed against. */
+
+#include <Windows.h>
+
+#include <algorithm>
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <cstdio>
+#include <limits>
+#include <string_view>
+#include <utility>
+
+#include "../../core/logging/log.h"
+#include "../../middleware/datagen/family4/loadout/loadout_resolver.h"
+#include "../build_data/runtime.h"
+#include "runtime.h"
+#include "state.h"
+#include "state_account_transaction_helpers.h"
+#include "storage/internal.h"
+
+namespace sunrise::state {
+namespace runtime::detail {
+
+namespace authored_inventory = account::inventory;
+namespace item_details = build_data::items::details;
+namespace inventory_buckets = build_data::inventory::buckets;
+namespace family4_loadout = middleware::datagen::family4::loadout;
+
+/** Equipment slots 0-2 are weapons and 3-7 are class-specific armor. */
+constexpr std::uint8_t kGearEquipmentSlotCount = 8;
+
+/** Writes one exhaustive item-dismantle transaction checkpoint. */
+void report_dismantle(std::string_view stage,
+                      std::string_view result,
+                      std::string_view reason,
+                      std::uint32_t definitionHash,
+                      std::uint64_t characterSoid,
+                      std::uint64_t instanceSoid,
+                      std::size_t inventoryIndex,
+                      std::uint16_t inventoryRow,
+                      std::uint8_t equipmentSlot,
+                      std::size_t movedItemCount,
+                      std::uint32_t nextInventorySerial) noexcept {
+    std::array<char, core::log::kLineCapacity> line{};
+    const int count =
+        std::snprintf(line.data(),
+                      line.size(),
+                      "ev=dismantle stage=%.*s result=%.*s reason=%.*s definition_hash=0x%08X "
+                      "character=0x%llX instance=0x%llX inventory_index=%zu inventory_row=%u "
+                      "equipment_slot=%u moved_items=%zu next_serial=%u",
+                      static_cast<int>(stage.size()),
+                      stage.data(),
+                      static_cast<int>(result.size()),
+                      result.data(),
+                      static_cast<int>(reason.size()),
+                      reason.data(),
+                      definitionHash,
+                      static_cast<unsigned long long>(characterSoid),
+                      static_cast<unsigned long long>(instanceSoid),
+                      inventoryIndex,
+                      static_cast<unsigned>(inventoryRow),
+                      static_cast<unsigned>(equipmentSlot),
+                      movedItemCount,
+                      nextInventorySerial);
+    if (count > 0) {
+        core::log::write(core::log::Channel::state,
+                         result == "ok" ? core::log::Level::debug : core::log::Level::warn,
+                         {line.data(), static_cast<std::size_t>(count)});
+    }
+}
+
+/**
+ * Credits the supported client's ordinary weapon/armor dismantle payout.
+ *
+ * Capped stacks
+ * lose only the overflowing part, matching normal profile-inventory behavior.
+ * Every credited row
+ * receives a new mutation serial so the account observer can display it.
+ */
+[[nodiscard]] bool
+apply_dismantle_rewards(const AccountState& before,
+                        std::uint8_t equipmentSlot,
+                        AccountState& after,
+                        std::array<DismantleReward, kDismantleRewardCapacity>& rewards,
+                        std::size_t& rewardCount) noexcept {
+    after = before;
+    rewards = {};
+    rewardCount = 0;
+    if (!valid_profile_inventory(before)) {
+        return false;
+    }
+    if (equipmentSlot >= kGearEquipmentSlotCount) {
+        return true;
+    }
+
+    std::int32_t greatestMutationSerial = 0;
+    for (std::size_t index = 0; index < before.profileItemCount; ++index) {
+        greatestMutationSerial =
+            (std::max)(greatestMutationSerial, before.profileItems[index].mutationSerial);
+    }
+
+    for (std::size_t policyIndex = 0; policyIndex < before.dismantleRewardCount; ++policyIndex) {
+        const DismantleRewardPolicy& policy = before.dismantleRewards[policyIndex];
+        build_data::items::Definition definition{};
+        item_details::Definition detail{};
+        inventory_buckets::Descriptor bucket{};
+        if (policy.definitionHash == authored_inventory::kNoDefinitionHash || policy.quantity <= 0
+            || !build_data::find_item_definition_hash(policy.definitionHash, definition)
+            || definition.definitionHash != policy.definitionHash
+            || !build_data::find_configured_item_detail(definition.definitionIndex, detail)
+            || detail.definitionIndex != definition.definitionIndex
+            || detail.definitionHash != definition.definitionHash
+            || detail.bucketId != definition.bucketId
+            || detail.instancedDefinitionState != item_details::InstancedDefinitionState::stackable
+            || detail.maxStackSize <= 0
+            || !build_data::find_inventory_bucket_descriptor(detail.bucketId, bucket)
+            || bucket.arraySelector != inventory_buckets::ArraySelector::profile
+            || build_data::is_profile_action_source(definition.definitionIndex,
+                                                    definition.bucketId)) {
+            return false;
+        }
+
+        std::size_t profileIndex = after.profileItemCount;
+        for (std::size_t index = 0; index < after.profileItemCount; ++index) {
+            const authored_inventory::ProfileItem& item = after.profileItems[index];
+            if (item.definitionHash != policy.definitionHash) {
+                continue;
+            }
+            if (item.instanceSoid != 0 || item.quantity <= 0
+                || item.quantity > detail.maxStackSize) {
+                return false;
+            }
+            if (profileIndex == after.profileItemCount && item.quantity < detail.maxStackSize) {
+                profileIndex = index;
+            }
+        }
+
+        const bool appended = profileIndex == after.profileItemCount;
+        if ((appended && after.profileItemCount >= after.profileItems.size())
+            || greatestMutationSerial == (std::numeric_limits<std::int32_t>::max)()) {
+            continue;
+        }
+        const std::int32_t previousQuantity =
+            appended ? 0 : after.profileItems[profileIndex].quantity;
+        const std::int32_t available = detail.maxStackSize - previousQuantity;
+        const std::int32_t credited = (std::min)(policy.quantity, available);
+        if (credited <= 0) {
+            continue;
+        }
+
+        AccountState candidate = after;
+        const std::int32_t mutationSerial = greatestMutationSerial + 1;
+        const std::int32_t afterQuantity = previousQuantity + credited;
+        if (appended) {
+            candidate.profileItems[profileIndex] = {
+                0, policy.definitionHash, afterQuantity, mutationSerial};
+            ++candidate.profileItemCount;
+        } else {
+            candidate.profileItems[profileIndex].quantity = afterQuantity;
+            candidate.profileItems[profileIndex].mutationSerial = mutationSerial;
+        }
+        // A full native bucket drops this reward, but never blocks deletion of the source item.
+        if (!account::valid(candidate) || !valid_profile_inventory(candidate)) {
+            continue;
+        }
+        if (rewardCount >= rewards.size()) {
+            return false;
+        }
+        after = candidate;
+        greatestMutationSerial = mutationSerial;
+        rewards[rewardCount++] = {
+            policy.definitionHash, profileIndex, credited, afterQuantity, mutationSerial};
+    }
+    return account::valid(after) && valid_profile_inventory(after);
+}
+
+/**
+ * Builds the one canonical dismantle transition for an exact account snapshot.
+ *
+ * Surviving authored entries keep their mutation generation unless installed row placement moves
+ * them. Generation capacity is checked for every move before any survivor is changed.
+ */
+[[nodiscard]] bool stage_item_dismantle(const AccountState& account,
+                                        std::size_t characterIndex,
+                                        std::uint64_t instanceSoid,
+                                        PendingItemDismantle& mutation) noexcept {
+    mutation = {};
+    if (instanceSoid == 0 || !account::valid(account) || characterIndex >= account.characterCount
+        || !account.characters[characterIndex].selected) {
+        return false;
+    }
+
+    const CharacterState& before = account.characters[characterIndex];
+    std::size_t inventoryIndex = before.inventory.count;
+    for (std::size_t index = 0; index < before.inventory.count; ++index) {
+        if (before.inventory.values[index].instanceSoid == instanceSoid) {
+            inventoryIndex = index;
+            break;
+        }
+    }
+    if (inventoryIndex >= before.inventory.count
+        || (before.inventory.values[inventoryIndex].flags & authored_inventory::kLockedItemFlag)
+               != 0) {
+        return false;
+    }
+
+    family4_loadout::ResolvedLoadout beforeLoadout{};
+    std::uint16_t dismantledRow = 0;
+    std::uint8_t dismantledSlot = 0;
+    if (!family4_loadout::resolve(account, characterIndex, beforeLoadout)
+        || before.nextInventorySerial
+               > static_cast<std::uint32_t>((std::numeric_limits<std::int32_t>::max)())
+        || !find_unequipped_row(beforeLoadout, instanceSoid, dismantledRow, dismantledSlot)) {
+        return false;
+    }
+
+    CharacterState after = before;
+    const authored_inventory::Item dismantledItem = after.inventory.values[inventoryIndex];
+    for (std::size_t index = inventoryIndex; index + 1U < after.inventory.count; ++index) {
+        after.inventory.values[index] = after.inventory.values[index + 1U];
+    }
+    --after.inventory.count;
+    after.inventory.values[after.inventory.count] = {};
+
+    AccountState candidate = account;
+    candidate.characters[characterIndex] = after;
+    family4_loadout::ResolvedLoadout placedAfter{};
+    if (!account::valid(candidate)
+        || !family4_loadout::resolve(candidate, characterIndex, placedAfter)
+        || loadout_contains(placedAfter, instanceSoid)
+        || beforeLoadout.itemCount != placedAfter.itemCount + 1U) {
+        return false;
+    }
+
+    std::size_t movedItemCount = 0;
+    for (std::size_t index = 0; index < after.inventory.count; ++index) {
+        const std::uint64_t survivorSoid = after.inventory.values[index].instanceSoid;
+        std::uint16_t beforeRow = 0;
+        std::uint16_t afterRow = 0;
+        std::uint8_t beforeSlot = 0;
+        std::uint8_t afterSlot = 0;
+        if (!find_unequipped_row(beforeLoadout, survivorSoid, beforeRow, beforeSlot)
+            || !find_unequipped_row(placedAfter, survivorSoid, afterRow, afterSlot)
+            || beforeSlot != afterSlot) {
+            return false;
+        }
+        movedItemCount += static_cast<std::size_t>(beforeRow != afterRow);
+    }
+
+    // The serial is signed on the wire, so it must stay inside the positive int32 range.
+    constexpr std::uint32_t kMaximumInventorySerial =
+        static_cast<std::uint32_t>((std::numeric_limits<std::int32_t>::max)());
+    if (after.nextInventorySerial > kMaximumInventorySerial
+        || movedItemCount > kMaximumInventorySerial - after.nextInventorySerial) {
+        return false;
+    }
+
+    for (std::size_t index = 0; index < after.inventory.count; ++index) {
+        const std::uint64_t survivorSoid = after.inventory.values[index].instanceSoid;
+        std::uint16_t beforeRow = 0;
+        std::uint16_t afterRow = 0;
+        std::uint8_t beforeSlot = 0;
+        std::uint8_t afterSlot = 0;
+        if (!find_unequipped_row(beforeLoadout, survivorSoid, beforeRow, beforeSlot)
+            || !find_unequipped_row(placedAfter, survivorSoid, afterRow, afterSlot)
+            || beforeSlot != afterSlot) {
+            return false;
+        }
+        if (beforeRow != afterRow) {
+            after.inventory.values[index].mutationSerial =
+                static_cast<std::int32_t>(after.nextInventorySerial++);
+        }
+    }
+
+    candidate.characters[characterIndex] = after;
+    family4_loadout::ResolvedLoadout checkedAfter{};
+    if (!account::valid(candidate)
+        || !family4_loadout::resolve(candidate, characterIndex, checkedAfter)
+        || checkedAfter.itemCount != placedAfter.itemCount
+        || loadout_contains(checkedAfter, instanceSoid)) {
+        return false;
+    }
+    for (std::size_t index = 0; index < after.inventory.count; ++index) {
+        const std::uint64_t survivorSoid = after.inventory.values[index].instanceSoid;
+        std::uint16_t placedRow = 0;
+        std::uint16_t checkedRow = 0;
+        std::uint8_t placedSlot = 0;
+        std::uint8_t checkedSlot = 0;
+        if (!find_unequipped_row(placedAfter, survivorSoid, placedRow, placedSlot)
+            || !find_unequipped_row(checkedAfter, survivorSoid, checkedRow, checkedSlot)
+            || placedRow != checkedRow || placedSlot != checkedSlot) {
+            return false;
+        }
+    }
+
+    build_data::items::Definition dismantledDefinition{};
+    item_details::Definition dismantledDetail{};
+    if (!build_data::find_item_definition_hash(dismantledItem.definitionHash, dismantledDefinition)
+        || dismantledDefinition.definitionHash != dismantledItem.definitionHash
+        || !build_data::find_configured_item_detail(dismantledDefinition.definitionIndex,
+                                                    dismantledDetail)
+        || dismantledDetail.definitionIndex != dismantledDefinition.definitionIndex
+        || dismantledDetail.definitionHash != dismantledDefinition.definitionHash
+        || dismantledDetail.bucketId != dismantledDefinition.bucketId
+        || dismantledDetail.instancedDefinitionState
+               != item_details::InstancedDefinitionState::instanced
+        || !dismantledDetail.equipmentSlot.has_value()
+        || static_cast<std::uint8_t>(*dismantledDetail.equipmentSlot) != dismantledSlot) {
+        return false;
+    }
+
+    AccountState rewarded{};
+    std::array<DismantleReward, kDismantleRewardCapacity> rewards{};
+    std::size_t rewardCount = 0;
+    if (!apply_dismantle_rewards(candidate, dismantledSlot, rewarded, rewards, rewardCount)) {
+        return false;
+    }
+    candidate = rewarded;
+
+    mutation.beforeCharacter = before;
+    mutation.afterCharacter = after;
+    mutation.beforeProfileItems = account.profileItems;
+    mutation.afterProfileItems = candidate.profileItems;
+    mutation.rewards = rewards;
+    mutation.dismantledItem = dismantledItem;
+    mutation.accountSoid = account.primarySoid;
+    mutation.characterSoid = before.soid;
+    mutation.dismantledInstanceSoid = instanceSoid;
+    mutation.characterIndex = characterIndex;
+    mutation.expectedInventoryCount = before.inventory.count;
+    mutation.expectedProfileItemCount = account.profileItemCount;
+    mutation.afterProfileItemCount = candidate.profileItemCount;
+    mutation.inventoryIndex = inventoryIndex;
+    mutation.movedInventoryItemCount = movedItemCount;
+    mutation.rewardCount = rewardCount;
+    mutation.inventoryRow = dismantledRow;
+    mutation.equipmentSlot = dismantledSlot;
+    mutation.profileChanged = rewardCount != 0;
+    mutation.prepared = true;
+    return true;
+}
+
+/** @return True when both descriptions name the same credited profile mutation. */
+[[nodiscard]] bool same_dismantle_reward(const DismantleReward& left,
+                                         const DismantleReward& right) noexcept {
+    return left.definitionHash == right.definitionHash && left.profileIndex == right.profileIndex
+           && left.quantity == right.quantity && left.afterQuantity == right.afterQuantity
+           && left.mutationSerial == right.mutationSerial;
+}
+
+/** @return True when two independently staged dismantles carry the exact same after-images. */
+[[nodiscard]] bool same_dismantle_transition(const PendingItemDismantle& left,
+                                             const PendingItemDismantle& right) noexcept {
+    if (left.prepared != right.prepared || left.accountSoid != right.accountSoid
+        || left.characterSoid != right.characterSoid
+        || left.dismantledInstanceSoid != right.dismantledInstanceSoid
+        || left.characterIndex != right.characterIndex
+        || left.expectedInventoryCount != right.expectedInventoryCount
+        || left.expectedProfileItemCount != right.expectedProfileItemCount
+        || left.afterProfileItemCount != right.afterProfileItemCount
+        || left.inventoryIndex != right.inventoryIndex
+        || left.movedInventoryItemCount != right.movedInventoryItemCount
+        || left.rewardCount != right.rewardCount || left.inventoryRow != right.inventoryRow
+        || left.equipmentSlot != right.equipmentSlot || left.profileChanged != right.profileChanged
+        || !same_stationary_item(left.dismantledItem, right.dismantledItem)
+        || !same_character(left.beforeCharacter, right.beforeCharacter)
+        || !same_character(left.afterCharacter, right.afterCharacter)
+        || !same_profile_views(left.beforeProfileItems,
+                               left.expectedProfileItemCount,
+                               right.beforeProfileItems,
+                               right.expectedProfileItemCount)
+        || !same_profile_views(left.afterProfileItems,
+                               left.afterProfileItemCount,
+                               right.afterProfileItems,
+                               right.afterProfileItemCount)) {
+        return false;
+    }
+    for (std::size_t index = 0; index < left.rewards.size(); ++index) {
+        if (!same_dismantle_reward(left.rewards[index], right.rewards[index])) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/** Applies a fully checked dismantle after-image over an exact current account view. */
+[[nodiscard]] bool materialize_item_dismantle(const AccountState& current,
+                                              const PendingItemDismantle& mutation,
+                                              AccountState& after) noexcept {
+    after = {};
+    if (!mutation.prepared || mutation.accountSoid == 0 || mutation.characterSoid == 0
+        || mutation.dismantledInstanceSoid == 0
+        || mutation.dismantledItem.instanceSoid != mutation.dismantledInstanceSoid
+        || mutation.dismantledItem.definitionHash == authored_inventory::kNoDefinitionHash
+        || mutation.characterIndex >= current.characterCount || mutation.expectedInventoryCount == 0
+        || mutation.expectedInventoryCount > authored_inventory::kCharacterItemCapacity
+        || mutation.expectedProfileItemCount > authored_inventory::kProfileItemCapacity
+        || mutation.afterProfileItemCount > authored_inventory::kProfileItemCapacity
+        || mutation.inventoryIndex >= mutation.expectedInventoryCount
+        || mutation.rewardCount > mutation.rewards.size()
+        || mutation.profileChanged != (mutation.rewardCount != 0)
+        || mutation.beforeCharacter.soid != mutation.characterSoid
+        || mutation.afterCharacter.soid != mutation.characterSoid
+        || mutation.beforeCharacter.inventory.count != mutation.expectedInventoryCount
+        || mutation.afterCharacter.inventory.count + 1U != mutation.expectedInventoryCount
+        || !same_stationary_item(mutation.beforeCharacter.inventory.values[mutation.inventoryIndex],
+                                 mutation.dismantledItem)
+        || current.primarySoid != mutation.accountSoid
+        || !same_profile_inventory(
+            current, mutation.beforeProfileItems, mutation.expectedProfileItemCount)) {
+        return false;
+    }
+    const CharacterState& character = current.characters[mutation.characterIndex];
+    if (!character.selected || character.soid != mutation.characterSoid
+        || !same_character(character, mutation.beforeCharacter)) {
+        return false;
+    }
+    for (std::size_t index = 0; index < mutation.rewards.size(); ++index) {
+        const DismantleReward& reward = mutation.rewards[index];
+        if (index < mutation.rewardCount) {
+            if (reward.definitionHash == authored_inventory::kNoDefinitionHash
+                || reward.profileIndex >= mutation.afterProfileItemCount || reward.quantity <= 0
+                || reward.afterQuantity < reward.quantity || reward.mutationSerial <= 0) {
+                return false;
+            }
+            const authored_inventory::ProfileItem& row =
+                mutation.afterProfileItems[reward.profileIndex];
+            if (row.instanceSoid != 0 || row.definitionHash != reward.definitionHash
+                || row.quantity != reward.afterQuantity
+                || row.mutationSerial != reward.mutationSerial) {
+                return false;
+            }
+        } else if (reward.definitionHash != 0 || reward.profileIndex != 0 || reward.quantity != 0
+                   || reward.afterQuantity != 0 || reward.mutationSerial != 0) {
+            return false;
+        }
+    }
+    if (!mutation.profileChanged
+        && !same_profile_views(mutation.beforeProfileItems,
+                               mutation.expectedProfileItemCount,
+                               mutation.afterProfileItems,
+                               mutation.afterProfileItemCount)) {
+        return false;
+    }
+
+    PendingItemDismantle canonical{};
+    if (!stage_item_dismantle(
+            current, mutation.characterIndex, mutation.dismantledInstanceSoid, canonical)
+        || !same_dismantle_transition(canonical, mutation)) {
+        return false;
+    }
+
+    after = current;
+    after.characters[mutation.characterIndex] = mutation.afterCharacter;
+    after.profileItems = mutation.afterProfileItems;
+    after.profileItemCount = mutation.afterProfileItemCount;
+    return account::valid(after) && valid_profile_inventory(after)
+           && !identity_uses_soid(after, mutation.dismantledInstanceSoid);
+}
+
+} // namespace runtime::detail
+} // namespace sunrise::state

Sunrise/src/state/runtime/state_account_equipment_runtime.cpp

@@ -0,0 +1,452 @@
+/**
+ * Equipment placement helpers: native and semantic slots, resolved positions, and the
+ * comparisons one equipment transition is checked against.
+ */
+
+#include <Windows.h>
+
+#include <algorithm>
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <cstdio>
+#include <limits>
+#include <string_view>
+#include <utility>
+
+#include "../../core/logging/log.h"
+#include "../../middleware/datagen/family4/loadout/loadout_resolver.h"
+#include "../build_data/runtime.h"
+#include "runtime.h"
+#include "state.h"
+#include "state_account_transaction_helpers.h"
+#include "storage/internal.h"
+
+namespace sunrise::state {
+namespace runtime::detail {
+
+namespace authored_inventory = account::inventory;
+namespace item_details = build_data::items::details;
+namespace inventory_buckets = build_data::inventory::buckets;
+namespace family4_loadout = middleware::datagen::family4::loadout;
+
+/** Resolves the installed native equipment slot for one configured authored item. */
+[[nodiscard]] bool native_equipment_slot(const authored_inventory::Item& item,
+                                         std::uint8_t& slot) noexcept {
+    build_data::items::Definition definition{};
+    item_details::Definition detail{};
+    if (!build_data::find_item_definition_hash(item.definitionHash, definition)
+        || definition.definitionHash != item.definitionHash
+        || !build_data::find_configured_item_detail(definition.definitionIndex, detail)
+        || detail.definitionIndex != definition.definitionIndex
+        || detail.definitionHash != definition.definitionHash
+        || detail.bucketId != definition.bucketId || !detail.equipmentSlot.has_value()
+        || *detail.equipmentSlot < 0
+        || static_cast<std::size_t>(*detail.equipmentSlot) >= item_details::kEquipmentSlotCount) {
+        return false;
+    }
+    slot = static_cast<std::uint8_t>(*detail.equipmentSlot);
+    return true;
+}
+
+/** Resolves the installed physical inventory bucket for one configured authored item. */
+[[nodiscard]] bool inventory_bucket_id(const authored_inventory::Item& item,
+                                       std::uint8_t& bucketId) noexcept {
+    build_data::items::Definition definition{};
+    item_details::Definition detail{};
+    if (!build_data::find_item_definition_hash(item.definitionHash, definition)
+        || definition.definitionHash != item.definitionHash
+        || !build_data::find_configured_item_detail(definition.definitionIndex, detail)
+        || detail.definitionIndex != definition.definitionIndex
+        || detail.definitionHash != definition.definitionHash
+        || detail.bucketId != definition.bucketId) {
+        return false;
+    }
+    bucketId = detail.bucketId;
+    return true;
+}
+
+/** Maps the 16 proven native equipment positions onto their stable authored State slots. */
+[[nodiscard]] bool semantic_equipment_slot(std::uint8_t nativeSlot,
+                                           std::size_t& semanticIndex) noexcept {
+    using EquipmentSlot = authored_inventory::EquipmentSlot;
+    EquipmentSlot semanticSlot = EquipmentSlot::count;
+    switch (nativeSlot) {
+    case 0:
+        semanticSlot = EquipmentSlot::subclass;
+        break;
+    case 1:
+        semanticSlot = EquipmentSlot::helmet;
+        break;
+    case 2:
+        semanticSlot = EquipmentSlot::gauntlets;
+        break;
+    case 4:
+        semanticSlot = EquipmentSlot::chest;
+        break;
+    case 5:
+        semanticSlot = EquipmentSlot::legs;
+        break;
+    case 6:
+        semanticSlot = EquipmentSlot::classItem;
+        break;
+    case 7:
+        semanticSlot = EquipmentSlot::kinetic;
+        break;
+    case 8:
+        semanticSlot = EquipmentSlot::energy;
+        break;
+    case 9:
+        semanticSlot = EquipmentSlot::heavy;
+        break;
+    case 10:
+        semanticSlot = EquipmentSlot::ship;
+        break;
+    case 11:
+        semanticSlot = EquipmentSlot::vehicle;
+        break;
+    case 12:
+        semanticSlot = EquipmentSlot::ghost;
+        break;
+    case 13:
+        semanticSlot = EquipmentSlot::emblem;
+        break;
+    case 14:
+        semanticSlot = EquipmentSlot::emote;
+        break;
+    case 15:
+        semanticSlot = EquipmentSlot::clanBanner;
+        break;
+    case 17:
+        semanticSlot = EquipmentSlot::finisher;
+        break;
+    default:
+        return false;
+    }
+    semanticIndex = static_cast<std::size_t>(semanticSlot);
+    return semanticIndex < authored_inventory::kEquipmentSlotCount;
+}
+
+/** Finds one instance exactly once in a checked, row-sorted loadout. */
+[[nodiscard]] bool find_resolved_position(const family4_loadout::ResolvedLoadout& loadout,
+                                          std::uint64_t instanceSoid,
+                                          ResolvedPosition& position) noexcept {
+    bool found = false;
+    for (std::size_t index = 0; index < loadout.itemCount; ++index) {
+        const family4_loadout::ResolvedItem& item = loadout.items[index];
+        if (item.instance.instanceSoid != instanceSoid) {
+            continue;
+        }
+        if (found) {
+            return false;
+        }
+        found = true;
+        position.inventoryRow = item.inventoryRow;
+        position.equipmentSlot = item.equipmentSlot;
+        position.equipped = item.equipped;
+        position.mutationSerial = item.mutationSerial;
+    }
+    return found;
+}
+
+/** @return True when the native placement and equipped marker are unchanged. */
+[[nodiscard]] bool same_position(const ResolvedPosition& left,
+                                 const ResolvedPosition& right) noexcept {
+    return left.inventoryRow == right.inventoryRow && left.equipmentSlot == right.equipmentSlot
+           && left.equipped == right.equipped;
+}
+
+/**
+ * Applies canonical mutation generations after one shape-only equipment transition.
+ *
+ * Every surviving instance must preserve its native bucket. A generation advances exactly when
+ * its published native row or equipped marker changes, and a second resolution proves that the
+ * stamped after-image retained the staged placement.
+ */
+[[nodiscard]] bool
+finalize_equipment_transition(const AccountState& account,
+                              std::size_t characterIndex,
+                              std::uint64_t requestedInstanceSoid,
+                              EquipmentMutationKind kind,
+                              std::uint8_t expectedNativeSlot,
+                              const family4_loadout::ResolvedLoadout& beforeLoadout,
+                              CharacterState& after,
+                              std::size_t& movedItemCount) noexcept {
+    movedItemCount = 0;
+    if (characterIndex >= account.characterCount || kind == EquipmentMutationKind::none) {
+        return false;
+    }
+
+    AccountState candidate = account;
+    candidate.characters[characterIndex] = after;
+    family4_loadout::ResolvedLoadout placedAfter{};
+    if (!account::valid(candidate)
+        || !family4_loadout::resolve(candidate, characterIndex, placedAfter)
+        || placedAfter.itemCount != beforeLoadout.itemCount) {
+        return false;
+    }
+
+    ResolvedPosition beforeRequested{};
+    ResolvedPosition afterRequested{};
+    if (!find_resolved_position(beforeLoadout, requestedInstanceSoid, beforeRequested)
+        || !find_resolved_position(placedAfter, requestedInstanceSoid, afterRequested)
+        || beforeRequested.equipmentSlot != expectedNativeSlot
+        || afterRequested.equipmentSlot != expectedNativeSlot
+        || (kind == EquipmentMutationKind::equip
+            && (beforeRequested.equipped || !afterRequested.equipped))
+        || (kind == EquipmentMutationKind::unequip
+            && (!beforeRequested.equipped || afterRequested.equipped))) {
+        return false;
+    }
+
+    const auto count_move = [&](const authored_inventory::Item& item) noexcept {
+        ResolvedPosition beforePosition{};
+        ResolvedPosition afterPosition{};
+        if (!find_resolved_position(beforeLoadout, item.instanceSoid, beforePosition)
+            || !find_resolved_position(placedAfter, item.instanceSoid, afterPosition)
+            || beforePosition.equipmentSlot != afterPosition.equipmentSlot) {
+            return false;
+        }
+        movedItemCount += static_cast<std::size_t>(!same_position(beforePosition, afterPosition));
+        return true;
+    };
+    for (const auto& item : after.equipment.slots) {
+        if (item.has_value() && !count_move(*item)) {
+            return false;
+        }
+    }
+    for (std::size_t index = 0; index < after.inventory.count; ++index) {
+        if (!count_move(after.inventory.values[index])) {
+            return false;
+        }
+    }
+
+    // The serial is signed on the wire, so it must stay inside the positive int32 range.
+    constexpr std::uint32_t kMaximumInventorySerial =
+        static_cast<std::uint32_t>((std::numeric_limits<std::int32_t>::max)());
+    if (movedItemCount == 0 || after.nextInventorySerial > kMaximumInventorySerial
+        || movedItemCount > kMaximumInventorySerial - after.nextInventorySerial) {
+        return false;
+    }
+
+    const auto stamp_move = [&](authored_inventory::Item& item) noexcept {
+        ResolvedPosition beforePosition{};
+        ResolvedPosition afterPosition{};
+        if (!find_resolved_position(beforeLoadout, item.instanceSoid, beforePosition)
+            || !find_resolved_position(placedAfter, item.instanceSoid, afterPosition)
+            || beforePosition.equipmentSlot != afterPosition.equipmentSlot) {
+            return false;
+        }
+        if (!same_position(beforePosition, afterPosition)) {
+            item.mutationSerial = static_cast<std::int32_t>(after.nextInventorySerial++);
+        }
+        return true;
+    };
+    for (auto& item : after.equipment.slots) {
+        if (item.has_value() && !stamp_move(*item)) {
+            return false;
+        }
+    }
+    for (std::size_t index = 0; index < after.inventory.count; ++index) {
+        if (!stamp_move(after.inventory.values[index])) {
+            return false;
+        }
+    }
+
+    candidate.characters[characterIndex] = after;
+    family4_loadout::ResolvedLoadout checkedAfter{};
+    if (!account::valid(candidate)
+        || !family4_loadout::resolve(candidate, characterIndex, checkedAfter)
+        || checkedAfter.itemCount != placedAfter.itemCount) {
+        return false;
+    }
+    for (const auto& item : after.equipment.slots) {
+        if (!item.has_value()) {
+            continue;
+        }
+        ResolvedPosition placed{};
+        ResolvedPosition checked{};
+        if (!find_resolved_position(placedAfter, item->instanceSoid, placed)
+            || !find_resolved_position(checkedAfter, item->instanceSoid, checked)
+            || !same_position(placed, checked) || checked.mutationSerial != item->mutationSerial) {
+            return false;
+        }
+    }
+    for (std::size_t index = 0; index < after.inventory.count; ++index) {
+        const authored_inventory::Item& item = after.inventory.values[index];
+        ResolvedPosition placed{};
+        ResolvedPosition checked{};
+        if (!find_resolved_position(placedAfter, item.instanceSoid, placed)
+            || !find_resolved_position(checkedAfter, item.instanceSoid, checked)
+            || !same_position(placed, checked) || checked.mutationSerial != item.mutationSerial) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/** @return True when two authored item values are identical, including socket policy and tail. */
+[[nodiscard]] bool same_item(const authored_inventory::Item& left,
+                             const authored_inventory::Item& right) noexcept {
+    return left.instanceSoid == right.instanceSoid && left.definitionHash == right.definitionHash
+           && left.level == right.level && left.quantity == right.quantity
+           && left.flags == right.flags && left.sockets.policy == right.sockets.policy
+           && left.sockets.plugCount == right.sockets.plugCount
+           && left.sockets.plugs == right.sockets.plugs;
+}
+
+/** Records one checked native item-state transition. */
+void report_item_state(std::string_view stage,
+                       std::string_view result,
+                       std::string_view reason,
+                       std::uint64_t characterSoid,
+                       std::uint64_t instanceSoid,
+                       std::uint16_t definitionIndex,
+                       std::uint32_t beforeFlags,
+                       std::uint32_t afterFlags,
+                       bool equipped,
+                       std::size_t itemIndex) noexcept {
+    std::array<char, core::log::kLineCapacity> line{};
+    const int count = std::snprintf(
+        line.data(),
+        line.size(),
+        "ev=item_state stage=%.*s result=%.*s reason=%.*s character=0x%llX instance=0x%llX "
+        "definition=%u flags_before=0x%X flags_after=0x%X equipped=%u item_index=%zu",
+        static_cast<int>(stage.size()),
+        stage.data(),
+        static_cast<int>(result.size()),
+        result.data(),
+        static_cast<int>(reason.size()),
+        reason.data(),
+        static_cast<unsigned long long>(characterSoid),
+        static_cast<unsigned long long>(instanceSoid),
+        static_cast<unsigned>(definitionIndex),
+        beforeFlags,
+        afterFlags,
+        equipped ? 1U : 0U,
+        itemIndex);
+    if (count > 0) {
+        core::log::write(core::log::Channel::state,
+                         result == "ok" ? core::log::Level::debug : core::log::Level::warn,
+                         {line.data(), static_cast<std::size_t>(count)});
+    }
+}
+
+/** Exact stationary-item comparison, including its inventory mutation generation. */
+[[nodiscard]] bool same_stationary_item(const authored_inventory::Item& left,
+                                        const authored_inventory::Item& right) noexcept {
+    return same_item(left, right) && left.mutationSerial == right.mutationSerial;
+}
+
+/** @return True when every item-bearing field of two character views is identical. */
+[[nodiscard]] bool same_loadout(const CharacterState& left, const CharacterState& right) noexcept {
+    if (left.soid != right.soid || left.selected != right.selected || left.race != right.race
+        || left.gender != right.gender || left.characterClass != right.characterClass
+        || left.level != right.level || left.accepted != right.accepted
+        || left.previewAvailable != right.previewAvailable
+        || left.appearanceValue != right.appearanceValue
+        || left.lastOrbitedDestination != right.lastOrbitedDestination
+        || left.contentBypass != right.contentBypass
+        || left.movementAbilityEntry != right.movementAbilityEntry
+        || left.grenadeAbilityEntry != right.grenadeAbilityEntry
+        || left.superAbilityEntry != right.superAbilityEntry
+        || left.meleeAbilityEntry != right.meleeAbilityEntry
+        || left.classAbilityEntry != right.classAbilityEntry
+        || left.nextInventorySerial != right.nextInventorySerial
+        || left.inventory.count != right.inventory.count) {
+        return false;
+    }
+    for (std::size_t index = 0; index < left.equipment.slots.size(); ++index) {
+        const auto& leftItem = left.equipment.slots[index];
+        const auto& rightItem = right.equipment.slots[index];
+        if (leftItem.has_value() != rightItem.has_value()
+            || (leftItem.has_value() && !same_stationary_item(*leftItem, *rightItem))) {
+            return false;
+        }
+    }
+    for (std::size_t index = 0; index < left.inventory.count; ++index) {
+        if (!same_stationary_item(left.inventory.values[index], right.inventory.values[index])) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/** Exact character comparison, including the canonical unused inventory tail. */
+[[nodiscard]] bool same_character(const CharacterState& left,
+                                  const CharacterState& right) noexcept {
+    if (!same_loadout(left, right)) {
+        return false;
+    }
+    for (std::size_t index = left.inventory.count; index < left.inventory.values.size(); ++index) {
+        if (!same_stationary_item(left.inventory.values[index], right.inventory.values[index])) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/** Finds one item SOID exactly once in the character's equipment and dense inventory. */
+[[nodiscard]] bool find_character_item_location(const CharacterState& character,
+                                                std::uint64_t instanceSoid,
+                                                CharacterItemLocation& location) noexcept {
+    location = {};
+    bool found = false;
+    for (std::size_t index = 0; index < character.equipment.slots.size(); ++index) {
+        const auto& item = character.equipment.slots[index];
+        if (!item.has_value() || item->instanceSoid != instanceSoid) {
+            continue;
+        }
+        if (found) {
+            return false;
+        }
+        found = true;
+        location = {index, true};
+    }
+    for (std::size_t index = 0; index < character.inventory.count; ++index) {
+        if (character.inventory.values[index].instanceSoid != instanceSoid) {
+            continue;
+        }
+        if (found) {
+            return false;
+        }
+        found = true;
+        location = {index, false};
+    }
+    return found;
+}
+
+/** Borrows an item at a previously validated authored location. */
+[[nodiscard]] const authored_inventory::Item*
+character_item_at(const CharacterState& character, const CharacterItemLocation& location) noexcept {
+    if (location.equipped) {
+        if (location.index >= character.equipment.slots.size()
+            || !character.equipment.slots[location.index].has_value()) {
+            return nullptr;
+        }
+        return &*character.equipment.slots[location.index];
+    }
+    if (location.index >= character.inventory.count) {
+        return nullptr;
+    }
+    return &character.inventory.values[location.index];
+}
+
+/** Borrows a mutable item at a previously validated authored location. */
+[[nodiscard]] authored_inventory::Item*
+character_item_at(CharacterState& character, const CharacterItemLocation& location) noexcept {
+    if (location.equipped) {
+        if (location.index >= character.equipment.slots.size()
+            || !character.equipment.slots[location.index].has_value()) {
+            return nullptr;
+        }
+        return &*character.equipment.slots[location.index];
+    }
+    if (location.index >= character.inventory.count) {
+        return nullptr;
+    }
+    return &character.inventory.values[location.index];
+}
+
+} // namespace runtime::detail
+} // namespace sunrise::state

Sunrise/src/state/runtime/state_account_identity_runtime.cpp

@@ -0,0 +1,211 @@
+/** Instance identity helpers: generated SOIDs, ownership tests, and loadout row lookups. */
+
+#include <Windows.h>
+
+#include <algorithm>
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <cstdio>
+#include <limits>
+#include <string_view>
+#include <utility>
+
+#include "../../core/logging/log.h"
+#include "../../middleware/datagen/family4/loadout/loadout_resolver.h"
+#include "../build_data/runtime.h"
+#include "runtime.h"
+#include "state.h"
+#include "state_account_transaction_helpers.h"
+#include "storage/internal.h"
+
+namespace sunrise::state {
+namespace runtime::detail {
+
+namespace authored_inventory = account::inventory;
+namespace item_details = build_data::items::details;
+namespace inventory_buckets = build_data::inventory::buckets;
+namespace family4_loadout = middleware::datagen::family4::loadout;
+
+/** First SOID reserved for item instances created by this local runtime. */
+constexpr std::uint64_t kFirstGeneratedItemSoid = 0x4000000000000001ULL;
+
+/** Returns one character-owned instance's definition hash for bounded transaction diagnostics. */
+[[nodiscard]] std::uint32_t character_item_definition_hash(const CharacterState& character,
+                                                           std::uint64_t instanceSoid) noexcept {
+    for (const auto& item : character.equipment.slots) {
+        if (item.has_value() && item->instanceSoid == instanceSoid) {
+            return item->definitionHash;
+        }
+    }
+    for (std::size_t index = 0; index < character.inventory.count; ++index) {
+        if (character.inventory.values[index].instanceSoid == instanceSoid) {
+            return character.inventory.values[index].definitionHash;
+        }
+    }
+    return 0;
+}
+
+/** @return True when any account, character, profile-stack, or character-item key owns one SOID. */
+[[nodiscard]] bool account_owns_soid(const AccountState& account, std::uint64_t soid) noexcept {
+    if (soid == 0 || account.primarySoid == soid) {
+        return true;
+    }
+    for (std::size_t index = 0; index < account.profileItemCount; ++index) {
+        if (account.profileItems[index].instanceSoid == soid) {
+            return true;
+        }
+    }
+    for (std::size_t characterIndex = 0; characterIndex < account.characterCount;
+         ++characterIndex) {
+        const CharacterState& character = account.characters[characterIndex];
+        if (character.soid == soid) {
+            return true;
+        }
+        for (const auto& item : character.equipment.slots) {
+            if (item.has_value() && item->instanceSoid == soid) {
+                return true;
+            }
+        }
+        for (std::size_t index = 0; index < character.inventory.count; ++index) {
+            if (character.inventory.values[index].instanceSoid == soid) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+/** Finds a fresh deterministic item-instance SOID without sharing any other identity key. */
+[[nodiscard]] bool next_item_instance_soid(const AccountState& account,
+                                           std::uint64_t& output) noexcept {
+    std::uint64_t candidate = kFirstGeneratedItemSoid;
+    for (std::size_t characterIndex = 0; characterIndex < account.characterCount;
+         ++characterIndex) {
+        const CharacterState& character = account.characters[characterIndex];
+        for (const auto& item : character.equipment.slots) {
+            if (!item.has_value() || item->instanceSoid < candidate) {
+                continue;
+            }
+            if (item->instanceSoid == (std::numeric_limits<std::uint64_t>::max)()) {
+                return false;
+            }
+            candidate = item->instanceSoid + 1U;
+        }
+        for (std::size_t index = 0; index < character.inventory.count; ++index) {
+            const std::uint64_t instanceSoid = character.inventory.values[index].instanceSoid;
+            if (instanceSoid < candidate) {
+                continue;
+            }
+            if (instanceSoid == (std::numeric_limits<std::uint64_t>::max)()) {
+                return false;
+            }
+            candidate = instanceSoid + 1U;
+        }
+    }
+    while (account_owns_soid(account, candidate)) {
+        if (candidate == (std::numeric_limits<std::uint64_t>::max)()) {
+            return false;
+        }
+        ++candidate;
+    }
+    output = candidate;
+    return output != 0;
+}
+
+/** Finds a collision-free SOID for one newly appended profile stack. */
+[[nodiscard]] bool next_profile_item_instance_soid(const AccountState& account,
+                                                   std::uint64_t& output) noexcept {
+    std::uint64_t candidate = authored_inventory::kFirstProfileItemInstanceSoid;
+    while (account_owns_soid(account, candidate)) {
+        if (candidate == (std::numeric_limits<std::uint64_t>::max)()) {
+            return false;
+        }
+        ++candidate;
+    }
+    output = candidate;
+    return output != 0;
+}
+
+/** @return True when an account or character identity already owns the candidate object key. */
+[[nodiscard]] bool identity_uses_soid(const AccountState& account, std::uint64_t soid) noexcept {
+    if (soid == 0 || account.primarySoid == soid) {
+        return true;
+    }
+    for (std::size_t index = 0; index < account.characterCount; ++index) {
+        if (account.characters[index].soid == soid) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/** Uses the character's strongest existing item as the neutral local Collections pull level. */
+[[nodiscard]] std::int32_t acquisition_level(const CharacterState& character) noexcept {
+    std::int32_t level = 0;
+    for (const auto& item : character.equipment.slots) {
+        if (item.has_value()) {
+            level = (std::max)(level, item->level);
+        }
+    }
+    for (std::size_t index = 0; index < character.inventory.count; ++index) {
+        level = (std::max)(level, character.inventory.values[index].level);
+    }
+    return level;
+}
+
+/** Finds the one resolved unequipped row created by an acquisition candidate. */
+[[nodiscard]] bool find_acquired_row(const family4_loadout::ResolvedLoadout& loadout,
+                                     std::uint64_t instanceSoid,
+                                     std::uint16_t& inventoryRow,
+                                     std::uint8_t& equipmentSlot) noexcept {
+    bool found = false;
+    for (std::size_t index = 0; index < loadout.itemCount; ++index) {
+        const family4_loadout::ResolvedItem& item = loadout.items[index];
+        if (item.instance.instanceSoid != instanceSoid) {
+            continue;
+        }
+        if (found || item.equipped) {
+            return false;
+        }
+        found = true;
+        inventoryRow = item.inventoryRow;
+        equipmentSlot = item.equipmentSlot;
+    }
+    return found;
+}
+
+/** Finds the unique resolved unequipped position for one instance. */
+[[nodiscard]] bool find_unequipped_row(const family4_loadout::ResolvedLoadout& loadout,
+                                       std::uint64_t instanceSoid,
+                                       std::uint16_t& inventoryRow,
+                                       std::uint8_t& equipmentSlot) noexcept {
+    bool found = false;
+    for (std::size_t index = 0; index < loadout.itemCount; ++index) {
+        const family4_loadout::ResolvedItem& item = loadout.items[index];
+        if (item.instance.instanceSoid != instanceSoid) {
+            continue;
+        }
+        if (found || item.equipped) {
+            return false;
+        }
+        found = true;
+        inventoryRow = item.inventoryRow;
+        equipmentSlot = item.equipmentSlot;
+    }
+    return found;
+}
+
+/** @return True when the resolved loadout still carries an instance with this key. */
+[[nodiscard]] bool loadout_contains(const family4_loadout::ResolvedLoadout& loadout,
+                                    std::uint64_t instanceSoid) noexcept {
+    for (std::size_t index = 0; index < loadout.itemCount; ++index) {
+        if (loadout.items[index].instance.instanceSoid == instanceSoid) {
+            return true;
+        }
+    }
+    return false;
+}
+
+} // namespace runtime::detail
+} // namespace sunrise::state

Sunrise/src/state/runtime/state_account_profile_runtime.cpp

@@ -0,0 +1,539 @@
+/**
+ * Profile-inventory helpers: the account-wide stacks, their checks, and the material
+ * costs an action charges against them.
+ */
+
+#include <Windows.h>
+
+#include <algorithm>
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <cstdio>
+#include <limits>
+#include <string_view>
+#include <utility>
+
+#include "../../core/logging/log.h"
+#include "../../middleware/datagen/family4/loadout/loadout_resolver.h"
+#include "../build_data/runtime.h"
+#include "runtime.h"
+#include "state.h"
+#include "state_account_transaction_helpers.h"
+#include "storage/internal.h"
+
+namespace sunrise::state {
+namespace runtime::detail {
+
+namespace authored_inventory = account::inventory;
+namespace item_details = build_data::items::details;
+namespace inventory_buckets = build_data::inventory::buckets;
+namespace family4_loadout = middleware::datagen::family4::loadout;
+
+/** Writes one bounded profile-stack acquisition checkpoint. */
+void report_profile_acquisition(std::string_view stage,
+                                std::string_view result,
+                                std::string_view reason,
+                                std::uint32_t definitionHash,
+                                std::uint64_t accountSoid,
+                                std::uint64_t instanceSoid,
+                                std::uint8_t bucketId,
+                                std::size_t profileIndex,
+                                std::size_t itemCount,
+                                std::int32_t previousQuantity,
+                                std::int32_t acquiredQuantity,
+                                bool appended) noexcept {
+    std::array<char, core::log::kLineCapacity> line{};
+    const int count = std::snprintf(
+        line.data(),
+        line.size(),
+        "ev=profile_acquire stage=%.*s result=%.*s reason=%.*s definition_hash=0x%08X "
+        "account=0x%llX instance=0x%llX bucket=%u profile_index=%zu item_count=%zu "
+        "quantity_before=%d "
+        "quantity_after=%d appended=%u",
+        static_cast<int>(stage.size()),
+        stage.data(),
+        static_cast<int>(result.size()),
+        result.data(),
+        static_cast<int>(reason.size()),
+        reason.data(),
+        definitionHash,
+        static_cast<unsigned long long>(accountSoid),
+        static_cast<unsigned long long>(instanceSoid),
+        static_cast<unsigned>(bucketId),
+        profileIndex,
+        itemCount,
+        previousQuantity,
+        acquiredQuantity,
+        static_cast<unsigned>(appended));
+    if (count > 0) {
+        core::log::write(core::log::Channel::state,
+                         result == "ok" ? core::log::Level::debug : core::log::Level::warn,
+                         {line.data(), static_cast<std::size_t>(count)});
+    }
+}
+
+/** @return True when two profile stack rows carry identical authored values. */
+[[nodiscard]] bool same_profile_item(const authored_inventory::ProfileItem& left,
+                                     const authored_inventory::ProfileItem& right) noexcept {
+    return left.instanceSoid == right.instanceSoid && left.definitionHash == right.definitionHash
+           && left.quantity == right.quantity && left.mutationSerial == right.mutationSerial;
+}
+
+/** @return True when a complete fixed profile inventory equals one captured view. */
+[[nodiscard]] bool
+same_profile_inventory(const AccountState& account,
+                       const std::array<authored_inventory::ProfileItem,
+                                        authored_inventory::kProfileItemCapacity>& expected,
+                       std::size_t expectedCount) noexcept {
+    if (account.profileItemCount != expectedCount) {
+        return false;
+    }
+    for (std::size_t index = 0; index < account.profileItems.size(); ++index) {
+        if (!same_profile_item(account.profileItems[index], expected[index])) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/** @return True when two fixed profile views, including their empty tails, are identical. */
+[[nodiscard]] bool same_profile_views(
+    const std::array<authored_inventory::ProfileItem, authored_inventory::kProfileItemCapacity>&
+        left,
+    std::size_t leftCount,
+    const std::array<authored_inventory::ProfileItem, authored_inventory::kProfileItemCapacity>&
+        right,
+    std::size_t rightCount) noexcept {
+    if (leftCount != rightCount) {
+        return false;
+    }
+    for (std::size_t index = 0; index < left.size(); ++index) {
+        if (!same_profile_item(left[index], right[index])) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/**
+ * Checks every dense profile stack and mirrors the account encoder's bucket-row placement.
+ * This keeps State rejection independent of whether a later push happens to have scratch space.
+ */
+[[nodiscard]] bool valid_profile_inventory(const AccountState& account) noexcept {
+    if (account.profileItemCount > account.profileItems.size()) {
+        return false;
+    }
+    // The bucket identity is one byte on the wire, so 256 covers every value one can carry.
+    constexpr std::size_t kBucketIdentityCapacity = 256;
+    std::array<std::uint16_t, kBucketIdentityCapacity> taken{};
+    std::array<bool, inventory_buckets::kProfileSlotCapacity> occupied{};
+    std::size_t actionSourceCount = 0;
+    for (std::size_t index = 0; index < account.profileItems.size(); ++index) {
+        const authored_inventory::ProfileItem& item = account.profileItems[index];
+        if (index >= account.profileItemCount) {
+            if (item.instanceSoid != 0 || item.definitionHash != 0 || item.quantity != 0
+                || item.mutationSerial != 0) {
+                return false;
+            }
+            continue;
+        }
+        build_data::items::Definition definition{};
+        item_details::Definition detail{};
+        inventory_buckets::Descriptor bucket{};
+        if (item.quantity <= 0 || item.mutationSerial < 0
+            || !build_data::find_item_definition_hash(item.definitionHash, definition)
+            || definition.definitionHash != item.definitionHash
+            || !build_data::find_configured_item_detail(definition.definitionIndex, detail)
+            || detail.definitionIndex != definition.definitionIndex
+            || detail.definitionHash != definition.definitionHash
+            || detail.bucketId != definition.bucketId
+            || detail.instancedDefinitionState != item_details::InstancedDefinitionState::stackable
+            || !build_data::find_inventory_bucket_descriptor(definition.bucketId, bucket)
+            || bucket.arraySelector != inventory_buckets::ArraySelector::profile) {
+            return false;
+        }
+        const bool actionSource =
+            build_data::is_profile_action_source(definition.definitionIndex, definition.bucketId);
+        if (actionSource != (item.instanceSoid != 0)
+            || (actionSource
+                && ++actionSourceCount > authored_inventory::kProfileActionSourceCapacity)) {
+            return false;
+        }
+        const std::uint16_t used = taken[definition.bucketId];
+        if (used >= bucket.slotCount) {
+            return false;
+        }
+        const std::size_t row = static_cast<std::size_t>(bucket.firstSlot) + used;
+        if (row >= occupied.size() || occupied[row]) {
+            return false;
+        }
+        occupied[row] = true;
+        taken[definition.bucketId] = static_cast<std::uint16_t>(used + 1U);
+    }
+    return true;
+}
+
+/** Resolved, aggregated material charge for one installed native requirement set. */
+struct MaterialCharge {
+    std::uint32_t definitionHash{};
+    std::uint64_t quantity{};
+    bool deleteOnAction{};
+};
+
+/**
+ * Validates one native material requirement set and applies its deletions to a copied account.
+ * Requirements which are not deleted still gate the action by balance. Material rows must be
+ * ordinary non-resident profile stacks; removing an instance-backed action source would also owe
+ * a resident release and is deliberately rejected here.
+ */
+template <typename Requirement>
+[[nodiscard]] bool apply_material_requirements(const AccountState& before,
+                                               std::span<const Requirement> requirements,
+                                               AccountState& after,
+                                               bool& changed) noexcept {
+    after = before;
+    changed = false;
+    if (requirements.size() > build_data::material_requirements::kRequirementCapacity) {
+        return false;
+    }
+
+    std::array<MaterialCharge, build_data::material_requirements::kRequirementCapacity> charges{};
+    std::size_t chargeCount = 0;
+    for (const Requirement& requirement : requirements) {
+        if (requirement.quantity == 0) {
+            continue;
+        }
+        build_data::items::Definition definition{};
+        item_details::Definition detail{};
+        inventory_buckets::Descriptor bucket{};
+        if (requirement.itemDefinitionIndex
+                == build_data::material_requirements::kUnavailableItemDefinitionIndex
+            || !build_data::find_item_definition_index(requirement.itemDefinitionIndex, definition)
+            || definition.definitionIndex != requirement.itemDefinitionIndex
+            || !build_data::find_configured_item_detail(requirement.itemDefinitionIndex, detail)
+            || detail.definitionIndex != requirement.itemDefinitionIndex
+            || detail.definitionHash != definition.definitionHash
+            || detail.bucketId != definition.bucketId
+            || detail.instancedDefinitionState != item_details::InstancedDefinitionState::stackable
+            || !build_data::find_inventory_bucket_descriptor(definition.bucketId, bucket)
+            || bucket.arraySelector != inventory_buckets::ArraySelector::profile
+            || build_data::is_profile_action_source(definition.definitionIndex,
+                                                    definition.bucketId)) {
+            return false;
+        }
+        std::size_t chargeIndex = chargeCount;
+        for (std::size_t existing = 0; existing < chargeCount; ++existing) {
+            if (charges[existing].definitionHash == definition.definitionHash
+                && charges[existing].deleteOnAction == requirement.deleteOnAction) {
+                chargeIndex = existing;
+                break;
+            }
+        }
+        if (chargeIndex == chargeCount) {
+            if (chargeCount >= charges.size()) {
+                return false;
+            }
+            charges[chargeCount].definitionHash = definition.definitionHash;
+            charges[chargeCount].deleteOnAction = requirement.deleteOnAction;
+            ++chargeCount;
+        }
+        if (charges[chargeIndex].quantity
+            > (std::numeric_limits<std::uint64_t>::max)() - requirement.quantity) {
+            return false;
+        }
+        charges[chargeIndex].quantity += requirement.quantity;
+    }
+
+    for (std::size_t charge = 0; charge < chargeCount; ++charge) {
+        std::uint64_t available = 0;
+        for (std::size_t index = 0; index < before.profileItemCount; ++index) {
+            const authored_inventory::ProfileItem& item = before.profileItems[index];
+            if (item.definitionHash != charges[charge].definitionHash) {
+                continue;
+            }
+            if (item.instanceSoid != 0 || item.quantity <= 0
+                || available > (std::numeric_limits<std::uint64_t>::max)()
+                                   - static_cast<std::uint64_t>(item.quantity)) {
+                return false;
+            }
+            available += static_cast<std::uint64_t>(item.quantity);
+        }
+        if (available < charges[charge].quantity) {
+            return false;
+        }
+    }
+
+    std::array<std::uint64_t, build_data::material_requirements::kRequirementCapacity> remaining{};
+    bool hasDeletion = false;
+    for (std::size_t charge = 0; charge < chargeCount; ++charge) {
+        if (charges[charge].deleteOnAction) {
+            remaining[charge] = charges[charge].quantity;
+            hasDeletion = true;
+        }
+    }
+    if (!hasDeletion) {
+        return true;
+    }
+
+    std::array<authored_inventory::ProfileItem, authored_inventory::kProfileItemCapacity>
+        compacted{};
+    std::size_t compactedCount = 0;
+    for (std::size_t index = 0; index < before.profileItemCount; ++index) {
+        authored_inventory::ProfileItem item = before.profileItems[index];
+        for (std::size_t charge = 0; charge < chargeCount; ++charge) {
+            if (remaining[charge] == 0 || item.definitionHash != charges[charge].definitionHash) {
+                continue;
+            }
+            const auto available = static_cast<std::uint64_t>(item.quantity);
+            const auto consumed = (std::min)(available, remaining[charge]);
+            item.quantity -= static_cast<std::int32_t>(consumed);
+            remaining[charge] -= consumed;
+        }
+        if (item.quantity != 0) {
+            if (compactedCount >= compacted.size()) {
+                return false;
+            }
+            compacted[compactedCount++] = item;
+        }
+    }
+    if (std::any_of(remaining.cbegin(),
+                    remaining.cbegin() + static_cast<std::ptrdiff_t>(chargeCount),
+                    [](std::uint64_t value) noexcept { return value != 0; })) {
+        return false;
+    }
+
+    std::int32_t greatestMutationSerial = 0;
+    for (std::size_t index = 0; index < before.profileItemCount; ++index) {
+        greatestMutationSerial =
+            (std::max)(greatestMutationSerial, before.profileItems[index].mutationSerial);
+    }
+    std::size_t changedRows = 0;
+    for (std::size_t index = 0; index < compactedCount; ++index) {
+        if (index >= before.profileItemCount
+            || !same_profile_item(compacted[index], before.profileItems[index])) {
+            ++changedRows;
+        }
+    }
+    if (changedRows > static_cast<std::size_t>((std::numeric_limits<std::int32_t>::max)()
+                                               - greatestMutationSerial)) {
+        return false;
+    }
+    for (std::size_t index = 0; index < compactedCount; ++index) {
+        if (index >= before.profileItemCount
+            || !same_profile_item(compacted[index], before.profileItems[index])) {
+            compacted[index].mutationSerial = ++greatestMutationSerial;
+        }
+    }
+    after.profileItems = compacted;
+    after.profileItemCount = compactedCount;
+    changed = !same_profile_inventory(after, before.profileItems, before.profileItemCount);
+    return changed && account::valid(after) && valid_profile_inventory(after);
+}
+
+/** Resolves one Collections row's installed cost without embedding any item or quantity policy. */
+[[nodiscard]] bool
+apply_collection_materials(const AccountState& before,
+                           const build_data::collectibles::Definition& collectible,
+                           AccountState& after,
+                           bool& changed) noexcept {
+    after = before;
+    changed = false;
+    if (collectible.materialRequirementCount == 0) {
+        return collectible.materialRequirementSetIndex
+                   == build_data::collectibles::kUnavailableMaterialRequirementSetIndex
+               && collectible.materialRequirementSetHash == 0;
+    }
+    if (collectible.materialRequirementCount > collectible.materialRequirements.size()
+        || collectible.materialRequirementSetIndex
+               == build_data::collectibles::kUnavailableMaterialRequirementSetIndex
+        || collectible.materialRequirementSetHash == 0) {
+        return false;
+    }
+    return apply_material_requirements(
+        before,
+        std::span(collectible.materialRequirements)
+            .first(static_cast<std::size_t>(collectible.materialRequirementCount)),
+        after,
+        changed);
+}
+
+/**
+ * Answers whether the account holds one applicable stack of a socket action source.
+ * @param account Account whose profile stacks are searched.
+ * @param definitionHash Plug definition the Client asked to apply.
+ * @return True when a profile stack of that definition holds at least one unit.
+ */
+[[nodiscard]] bool holds_plug_source(const AccountState& account,
+                                     std::uint32_t definitionHash) noexcept {
+    for (std::size_t index = 0; index < account.profileItemCount; ++index) {
+        const authored_inventory::ProfileItem& item = account.profileItems[index];
+        if (item.definitionHash == definitionHash && item.quantity > 0) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * Takes one unit of an owned socket action source, releasing the row when its last unit goes.
+ *
+ * An action source is an instanced profile row, so the authored-cost path cannot spend it. The
+ * row keeps its identity and position while units remain, because the Client addresses it by that
+ * identity. An emptied row is removed and the rows after it move up, which is the same shape the
+ * authored-cost path leaves behind when a stack empties.
+ *
+ * @param account Account whose profile stacks are spent in place.
+ * @param definitionHash Plug definition being applied.
+ * @return True when one unit was taken.
+ */
+[[nodiscard]] bool spend_plug_source(AccountState& account, std::uint32_t definitionHash) noexcept {
+    std::size_t row = account.profileItemCount;
+    for (std::size_t index = 0; index < account.profileItemCount; ++index) {
+        if (account.profileItems[index].definitionHash == definitionHash
+            && account.profileItems[index].quantity > 0) {
+            row = index;
+            break;
+        }
+    }
+    if (row >= account.profileItemCount) {
+        return false;
+    }
+    if (--account.profileItems[row].quantity > 0) {
+        return true;
+    }
+    for (std::size_t index = row; index + 1U < account.profileItemCount; ++index) {
+        account.profileItems[index] = account.profileItems[index + 1U];
+    }
+    account.profileItems[--account.profileItemCount] = {};
+    return true;
+}
+
+/** Applies one dense installed action-cost set resolved from the selected plug or action row. */
+[[nodiscard]] bool
+apply_action_materials(const AccountState& before,
+                       const build_data::material_requirements::Definition& definition,
+                       AccountState& after,
+                       bool& changed) noexcept {
+    if (definition.requirementSetHash == 0
+        || definition.requirementSetIndex == build_data::material_requirements::kUnavailableSetIndex
+        || definition.requirementCount == 0
+        || definition.requirementCount > definition.requirements.size()) {
+        after = {};
+        changed = false;
+        return false;
+    }
+    for (std::size_t index = 0; index < definition.requirementCount; ++index) {
+        if (definition.requirements[index].condition
+            != build_data::material_requirements::kUnconditionalRequirement) {
+            after = {};
+            changed = false;
+            return false;
+        }
+    }
+    return apply_material_requirements(
+        before,
+        std::span(definition.requirements)
+            .first(static_cast<std::size_t>(definition.requirementCount)),
+        after,
+        changed);
+}
+
+/** @return True when a pending profile acquisition carries canonical dense before/after images. */
+[[nodiscard]] bool
+valid_profile_mutation_shape(const PendingProfileItemAcquisition& mutation) noexcept {
+    if (!mutation.prepared || mutation.accountSoid == 0
+        || mutation.actionSource != (mutation.acquiredInstanceSoid != 0)
+        || mutation.acquiredDefinitionHash == authored_inventory::kNoDefinitionHash
+        || mutation.expectedItemCount > authored_inventory::kProfileItemCapacity
+        || mutation.afterItemCount > authored_inventory::kProfileItemCapacity
+        || mutation.profileIndex >= mutation.afterItemCount || mutation.previousQuantity < 0
+        || mutation.acquiredQuantity <= mutation.previousQuantity
+        || mutation.acquiredQuantity - mutation.previousQuantity != 1
+        || mutation.previousMutationSerial < 0
+        || mutation.acquiredMutationSerial <= mutation.previousMutationSerial) {
+        return false;
+    }
+    if (mutation.appended) {
+        if (mutation.afterItemCount == 0 || mutation.previousQuantity != 0) {
+            return false;
+        }
+    } else if (mutation.previousQuantity == 0) {
+        return false;
+    }
+
+    bool foundBeforeTarget = mutation.appended;
+    for (std::size_t index = 0; index < mutation.beforeItems.size(); ++index) {
+        const authored_inventory::ProfileItem& before = mutation.beforeItems[index];
+        const authored_inventory::ProfileItem& after = mutation.afterItems[index];
+        if (index < mutation.expectedItemCount
+            && before.mutationSerial >= mutation.acquiredMutationSerial) {
+            return false;
+        }
+        if (index >= mutation.expectedItemCount
+            && (before.instanceSoid != 0 || before.definitionHash != 0 || before.quantity != 0
+                || before.mutationSerial != 0)) {
+            return false;
+        }
+        if (index >= mutation.afterItemCount
+            && (after.instanceSoid != 0 || after.definitionHash != 0 || after.quantity != 0
+                || after.mutationSerial != 0)) {
+            return false;
+        }
+        if (!mutation.appended && index < mutation.expectedItemCount
+            && before.instanceSoid == mutation.acquiredInstanceSoid
+            && before.definitionHash == mutation.acquiredDefinitionHash
+            && before.quantity == mutation.previousQuantity
+            && before.mutationSerial == mutation.previousMutationSerial) {
+            if (foundBeforeTarget) {
+                return false;
+            }
+            foundBeforeTarget = true;
+        }
+    }
+    const authored_inventory::ProfileItem& acquired = mutation.afterItems[mutation.profileIndex];
+    return foundBeforeTarget && acquired.instanceSoid == mutation.acquiredInstanceSoid
+           && acquired.definitionHash == mutation.acquiredDefinitionHash
+           && acquired.quantity == mutation.acquiredQuantity
+           && acquired.mutationSerial == mutation.acquiredMutationSerial;
+}
+
+/** Applies one validated pending profile after-image over a current, matching account. */
+[[nodiscard]] bool materialize_profile_acquisition(const AccountState& current,
+                                                   const PendingProfileItemAcquisition& mutation,
+                                                   AccountState& after) noexcept {
+    if (!valid_profile_mutation_shape(mutation) || current.primarySoid != mutation.accountSoid
+        || !same_profile_inventory(current, mutation.beforeItems, mutation.expectedItemCount)) {
+        return false;
+    }
+    item_details::Definition detail{};
+    inventory_buckets::Descriptor bucket{};
+    build_data::items::Definition item{};
+    build_data::collectibles::Definition collectible{};
+    if (!build_data::find_collectible_definition(mutation.collectibleIndex, collectible)
+        || collectible.itemDefinitionIndex
+               == build_data::collectibles::kUnavailableItemDefinitionIndex
+        || collectible.materialRequirementSetHash != mutation.materialRequirementSetHash
+        || collectible.materialRequirementCount != mutation.materialRequirementCount
+        || !build_data::find_item_definition_hash(mutation.acquiredDefinitionHash, item)
+        || collectible.itemDefinitionIndex != item.definitionIndex
+        || !build_data::find_configured_item_detail(item.definitionIndex, detail)
+        || detail.definitionHash != mutation.acquiredDefinitionHash
+        || detail.definitionIndex != item.definitionIndex || detail.bucketId != item.bucketId
+        || detail.bucketId != mutation.bucketId
+        || detail.instancedDefinitionState != item_details::InstancedDefinitionState::stackable
+        || detail.maxStackSize <= 0 || mutation.acquiredQuantity > detail.maxStackSize
+        || !build_data::find_inventory_bucket_descriptor(detail.bucketId, bucket)
+        || bucket.arraySelector != inventory_buckets::ArraySelector::profile
+        || build_data::is_profile_action_source(item.definitionIndex, item.bucketId)
+               != mutation.actionSource) {
+        return false;
+    }
+    after = current;
+    after.profileItems = mutation.afterItems;
+    after.profileItemCount = mutation.afterItemCount;
+    return account::valid(after) && valid_profile_inventory(after);
+}
+
+} // namespace runtime::detail
+} // namespace sunrise::state

Sunrise/src/state/runtime/state_account_runtime.cpp

@@ -1,4 +1,4 @@
-#include <Windows.h>
+#include <Windows.h>
 
 #include <algorithm>
 #include <array>
@@ -25,12 +25,6 @@ namespace item_details = build_data::items::details;
 namespace inventory_buckets = build_data::inventory::buckets;
 namespace family4_loadout = middleware::datagen::family4::loadout;
 
-/** First SOID reserved for item instances created by this local runtime. */
-constexpr std::uint64_t kFirstGeneratedItemSoid = 0x4000000000000001ULL;
-
-/** Equipment slots 0-2 are weapons and 3-7 are class-specific armor. */
-constexpr std::uint8_t kGearEquipmentSlotCount = 8;
-
 /** Writes one exhaustive equipment-transaction checkpoint to the persistent diagnostic log. */
 void report_equipment(std::string_view stage,
                       std::string_view result,
@@ -111,1873 +105,6 @@ void report_acquisition(std::string_view stage,
     }
 }
 
-/** Writes one bounded profile-stack acquisition checkpoint. */
-void report_profile_acquisition(std::string_view stage,
-                                std::string_view result,
-                                std::string_view reason,
-                                std::uint32_t definitionHash,
-                                std::uint64_t accountSoid,
-                                std::uint64_t instanceSoid,
-                                std::uint8_t bucketId,
-                                std::size_t profileIndex,
-                                std::size_t itemCount,
-                                std::int32_t previousQuantity,
-                                std::int32_t acquiredQuantity,
-                                bool appended) noexcept {
-    std::array<char, core::log::kLineCapacity> line{};
-    const int count = std::snprintf(
-        line.data(),
-        line.size(),
-        "ev=profile_acquire stage=%.*s result=%.*s reason=%.*s definition_hash=0x%08X "
-        "account=0x%llX instance=0x%llX bucket=%u profile_index=%zu item_count=%zu "
-        "quantity_before=%d "
-        "quantity_after=%d appended=%u",
-        static_cast<int>(stage.size()),
-        stage.data(),
-        static_cast<int>(result.size()),
-        result.data(),
-        static_cast<int>(reason.size()),
-        reason.data(),
-        definitionHash,
-        static_cast<unsigned long long>(accountSoid),
-        static_cast<unsigned long long>(instanceSoid),
-        static_cast<unsigned>(bucketId),
-        profileIndex,
-        itemCount,
-        previousQuantity,
-        acquiredQuantity,
-        static_cast<unsigned>(appended));
-    if (count > 0) {
-        core::log::write(core::log::Channel::state,
-                         result == "ok" ? core::log::Level::debug : core::log::Level::warn,
-                         {line.data(), static_cast<std::size_t>(count)});
-    }
-}
-
-/** @return True when two profile stack rows carry identical authored values. */
-[[nodiscard]] bool same_profile_item(const authored_inventory::ProfileItem& left,
-                                     const authored_inventory::ProfileItem& right) noexcept {
-    return left.instanceSoid == right.instanceSoid && left.definitionHash == right.definitionHash
-           && left.quantity == right.quantity && left.mutationSerial == right.mutationSerial;
-}
-
-/** @return True when a complete fixed profile inventory equals one captured view. */
-[[nodiscard]] bool
-same_profile_inventory(const AccountState& account,
-                       const std::array<authored_inventory::ProfileItem,
-                                        authored_inventory::kProfileItemCapacity>& expected,
-                       std::size_t expectedCount) noexcept {
-    if (account.profileItemCount != expectedCount) {
-        return false;
-    }
-    for (std::size_t index = 0; index < account.profileItems.size(); ++index) {
-        if (!same_profile_item(account.profileItems[index], expected[index])) {
-            return false;
-        }
-    }
-    return true;
-}
-
-/** @return True when two fixed profile views, including their empty tails, are identical. */
-[[nodiscard]] bool same_profile_views(
-    const std::array<authored_inventory::ProfileItem, authored_inventory::kProfileItemCapacity>&
-        left,
-    std::size_t leftCount,
-    const std::array<authored_inventory::ProfileItem, authored_inventory::kProfileItemCapacity>&
-        right,
-    std::size_t rightCount) noexcept {
-    if (leftCount != rightCount) {
-        return false;
-    }
-    for (std::size_t index = 0; index < left.size(); ++index) {
-        if (!same_profile_item(left[index], right[index])) {
-            return false;
-        }
-    }
-    return true;
-}
-
-/**
- * Checks every dense profile stack and mirrors the account encoder's bucket-row placement.
- * This keeps State rejection independent of whether a later push happens to have scratch space.
- */
-[[nodiscard]] bool valid_profile_inventory(const AccountState& account) noexcept {
-    if (account.profileItemCount > account.profileItems.size()) {
-        return false;
-    }
-    // The bucket identity is one byte on the wire, so 256 covers every value one can carry.
-    constexpr std::size_t kBucketIdentityCapacity = 256;
-    std::array<std::uint16_t, kBucketIdentityCapacity> taken{};
-    std::array<bool, inventory_buckets::kProfileSlotCapacity> occupied{};
-    std::size_t actionSourceCount = 0;
-    for (std::size_t index = 0; index < account.profileItems.size(); ++index) {
-        const authored_inventory::ProfileItem& item = account.profileItems[index];
-        if (index >= account.profileItemCount) {
-            if (item.instanceSoid != 0 || item.definitionHash != 0 || item.quantity != 0
-                || item.mutationSerial != 0) {
-                return false;
-            }
-            continue;
-        }
-        build_data::items::Definition definition{};
-        item_details::Definition detail{};
-        inventory_buckets::Descriptor bucket{};
-        if (item.quantity <= 0 || item.mutationSerial < 0
-            || !build_data::find_item_definition_hash(item.definitionHash, definition)
-            || definition.definitionHash != item.definitionHash
-            || !build_data::find_configured_item_detail(definition.definitionIndex, detail)
-            || detail.definitionIndex != definition.definitionIndex
-            || detail.definitionHash != definition.definitionHash
-            || detail.bucketId != definition.bucketId
-            || detail.instancedDefinitionState != item_details::InstancedDefinitionState::stackable
-            || !build_data::find_inventory_bucket_descriptor(definition.bucketId, bucket)
-            || bucket.arraySelector != inventory_buckets::ArraySelector::profile) {
-            return false;
-        }
-        const bool actionSource =
-            build_data::is_profile_action_source(definition.definitionIndex, definition.bucketId);
-        if (actionSource != (item.instanceSoid != 0)
-            || (actionSource
-                && ++actionSourceCount > authored_inventory::kProfileActionSourceCapacity)) {
-            return false;
-        }
-        const std::uint16_t used = taken[definition.bucketId];
-        if (used >= bucket.slotCount) {
-            return false;
-        }
-        const std::size_t row = static_cast<std::size_t>(bucket.firstSlot) + used;
-        if (row >= occupied.size() || occupied[row]) {
-            return false;
-        }
-        occupied[row] = true;
-        taken[definition.bucketId] = static_cast<std::uint16_t>(used + 1U);
-    }
-    return true;
-}
-
-/** Resolved, aggregated material charge for one installed native requirement set. */
-struct MaterialCharge {
-    std::uint32_t definitionHash{};
-    std::uint64_t quantity{};
-    bool deleteOnAction{};
-};
-
-/**
- * Validates one native material requirement set and applies its deletions to a copied account.
- * Requirements which are not deleted still gate the action by balance. Material rows must be
- * ordinary non-resident profile stacks; removing an instance-backed action source would also owe
- * a resident release and is deliberately rejected here.
- */
-template <typename Requirement>
-[[nodiscard]] bool apply_material_requirements(const AccountState& before,
-                                               std::span<const Requirement> requirements,
-                                               AccountState& after,
-                                               bool& changed) noexcept {
-    after = before;
-    changed = false;
-    if (requirements.size() > build_data::material_requirements::kRequirementCapacity) {
-        return false;
-    }
-
-    std::array<MaterialCharge, build_data::material_requirements::kRequirementCapacity> charges{};
-    std::size_t chargeCount = 0;
-    for (const Requirement& requirement : requirements) {
-        if (requirement.quantity == 0) {
-            continue;
-        }
-        build_data::items::Definition definition{};
-        item_details::Definition detail{};
-        inventory_buckets::Descriptor bucket{};
-        if (requirement.itemDefinitionIndex
-                == build_data::material_requirements::kUnavailableItemDefinitionIndex
-            || !build_data::find_item_definition_index(requirement.itemDefinitionIndex, definition)
-            || definition.definitionIndex != requirement.itemDefinitionIndex
-            || !build_data::find_configured_item_detail(requirement.itemDefinitionIndex, detail)
-            || detail.definitionIndex != requirement.itemDefinitionIndex
-            || detail.definitionHash != definition.definitionHash
-            || detail.bucketId != definition.bucketId
-            || detail.instancedDefinitionState != item_details::InstancedDefinitionState::stackable
-            || !build_data::find_inventory_bucket_descriptor(definition.bucketId, bucket)
-            || bucket.arraySelector != inventory_buckets::ArraySelector::profile
-            || build_data::is_profile_action_source(definition.definitionIndex,
-                                                    definition.bucketId)) {
-            return false;
-        }
-        std::size_t chargeIndex = chargeCount;
-        for (std::size_t existing = 0; existing < chargeCount; ++existing) {
-            if (charges[existing].definitionHash == definition.definitionHash
-                && charges[existing].deleteOnAction == requirement.deleteOnAction) {
-                chargeIndex = existing;
-                break;
-            }
-        }
-        if (chargeIndex == chargeCount) {
-            if (chargeCount >= charges.size()) {
-                return false;
-            }
-            charges[chargeCount].definitionHash = definition.definitionHash;
-            charges[chargeCount].deleteOnAction = requirement.deleteOnAction;
-            ++chargeCount;
-        }
-        if (charges[chargeIndex].quantity
-            > (std::numeric_limits<std::uint64_t>::max)() - requirement.quantity) {
-            return false;
-        }
-        charges[chargeIndex].quantity += requirement.quantity;
-    }
-
-    for (std::size_t charge = 0; charge < chargeCount; ++charge) {
-        std::uint64_t available = 0;
-        for (std::size_t index = 0; index < before.profileItemCount; ++index) {
-            const authored_inventory::ProfileItem& item = before.profileItems[index];
-            if (item.definitionHash != charges[charge].definitionHash) {
-                continue;
-            }
-            if (item.instanceSoid != 0 || item.quantity <= 0
-                || available > (std::numeric_limits<std::uint64_t>::max)()
-                                   - static_cast<std::uint64_t>(item.quantity)) {
-                return false;
-            }
-            available += static_cast<std::uint64_t>(item.quantity);
-        }
-        if (available < charges[charge].quantity) {
-            return false;
-        }
-    }
-
-    std::array<std::uint64_t, build_data::material_requirements::kRequirementCapacity> remaining{};
-    bool hasDeletion = false;
-    for (std::size_t charge = 0; charge < chargeCount; ++charge) {
-        if (charges[charge].deleteOnAction) {
-            remaining[charge] = charges[charge].quantity;
-            hasDeletion = true;
-        }
-    }
-    if (!hasDeletion) {
-        return true;
-    }
-
-    std::array<authored_inventory::ProfileItem, authored_inventory::kProfileItemCapacity>
-        compacted{};
-    std::size_t compactedCount = 0;
-    for (std::size_t index = 0; index < before.profileItemCount; ++index) {
-        authored_inventory::ProfileItem item = before.profileItems[index];
-        for (std::size_t charge = 0; charge < chargeCount; ++charge) {
-            if (remaining[charge] == 0 || item.definitionHash != charges[charge].definitionHash) {
-                continue;
-            }
-            const auto available = static_cast<std::uint64_t>(item.quantity);
-            const auto consumed = (std::min)(available, remaining[charge]);
-            item.quantity -= static_cast<std::int32_t>(consumed);
-            remaining[charge] -= consumed;
-        }
-        if (item.quantity != 0) {
-            if (compactedCount >= compacted.size()) {
-                return false;
-            }
-            compacted[compactedCount++] = item;
-        }
-    }
-    if (std::any_of(remaining.cbegin(),
-                    remaining.cbegin() + static_cast<std::ptrdiff_t>(chargeCount),
-                    [](std::uint64_t value) noexcept { return value != 0; })) {
-        return false;
-    }
-
-    std::int32_t greatestMutationSerial = 0;
-    for (std::size_t index = 0; index < before.profileItemCount; ++index) {
-        greatestMutationSerial =
-            (std::max)(greatestMutationSerial, before.profileItems[index].mutationSerial);
-    }
-    std::size_t changedRows = 0;
-    for (std::size_t index = 0; index < compactedCount; ++index) {
-        if (index >= before.profileItemCount
-            || !same_profile_item(compacted[index], before.profileItems[index])) {
-            ++changedRows;
-        }
-    }
-    if (changedRows > static_cast<std::size_t>((std::numeric_limits<std::int32_t>::max)()
-                                               - greatestMutationSerial)) {
-        return false;
-    }
-    for (std::size_t index = 0; index < compactedCount; ++index) {
-        if (index >= before.profileItemCount
-            || !same_profile_item(compacted[index], before.profileItems[index])) {
-            compacted[index].mutationSerial = ++greatestMutationSerial;
-        }
-    }
-    after.profileItems = compacted;
-    after.profileItemCount = compactedCount;
-    changed = !same_profile_inventory(after, before.profileItems, before.profileItemCount);
-    return changed && account::valid(after) && valid_profile_inventory(after);
-}
-
-/** Resolves one Collections row's installed cost without embedding any item or quantity policy. */
-[[nodiscard]] bool
-apply_collection_materials(const AccountState& before,
-                           const build_data::collectibles::Definition& collectible,
-                           AccountState& after,
-                           bool& changed) noexcept {
-    after = before;
-    changed = false;
-    if (collectible.materialRequirementCount == 0) {
-        return collectible.materialRequirementSetIndex
-                   == build_data::collectibles::kUnavailableMaterialRequirementSetIndex
-               && collectible.materialRequirementSetHash == 0;
-    }
-    if (collectible.materialRequirementCount > collectible.materialRequirements.size()
-        || collectible.materialRequirementSetIndex
-               == build_data::collectibles::kUnavailableMaterialRequirementSetIndex
-        || collectible.materialRequirementSetHash == 0) {
-        return false;
-    }
-    return apply_material_requirements(
-        before,
-        std::span(collectible.materialRequirements)
-            .first(static_cast<std::size_t>(collectible.materialRequirementCount)),
-        after,
-        changed);
-}
-
-/**
- * Answers whether the account holds one applicable stack of a socket action source.
- * @param account Account whose profile stacks are searched.
- * @param definitionHash Plug definition the Client asked to apply.
- * @return True when a profile stack of that definition holds at least one unit.
- */
-[[nodiscard]] bool holds_plug_source(const AccountState& account,
-                                     std::uint32_t definitionHash) noexcept {
-    for (std::size_t index = 0; index < account.profileItemCount; ++index) {
-        const authored_inventory::ProfileItem& item = account.profileItems[index];
-        if (item.definitionHash == definitionHash && item.quantity > 0) {
-            return true;
-        }
-    }
-    return false;
-}
-
-/**
- * Takes one unit of an owned socket action source, releasing the row when its last unit goes.
- *
- * An action source is an instanced profile row, so the authored-cost path cannot spend it. The
- * row keeps its identity and position while units remain, because the Client addresses it by that
- * identity. An emptied row is removed and the rows after it move up, which is the same shape the
- * authored-cost path leaves behind when a stack empties.
- *
- * @param account Account whose profile stacks are spent in place.
- * @param definitionHash Plug definition being applied.
- * @return True when one unit was taken.
- */
-[[nodiscard]] bool spend_plug_source(AccountState& account, std::uint32_t definitionHash) noexcept {
-    std::size_t row = account.profileItemCount;
-    for (std::size_t index = 0; index < account.profileItemCount; ++index) {
-        if (account.profileItems[index].definitionHash == definitionHash
-            && account.profileItems[index].quantity > 0) {
-            row = index;
-            break;
-        }
-    }
-    if (row >= account.profileItemCount) {
-        return false;
-    }
-    if (--account.profileItems[row].quantity > 0) {
-        return true;
-    }
-    for (std::size_t index = row; index + 1U < account.profileItemCount; ++index) {
-        account.profileItems[index] = account.profileItems[index + 1U];
-    }
-    account.profileItems[--account.profileItemCount] = {};
-    return true;
-}
-
-/** Applies one dense installed action-cost set resolved from the selected plug or action row. */
-[[nodiscard]] bool
-apply_action_materials(const AccountState& before,
-                       const build_data::material_requirements::Definition& definition,
-                       AccountState& after,
-                       bool& changed) noexcept {
-    if (definition.requirementSetHash == 0
-        || definition.requirementSetIndex == build_data::material_requirements::kUnavailableSetIndex
-        || definition.requirementCount == 0
-        || definition.requirementCount > definition.requirements.size()) {
-        after = {};
-        changed = false;
-        return false;
-    }
-    for (std::size_t index = 0; index < definition.requirementCount; ++index) {
-        if (definition.requirements[index].condition
-            != build_data::material_requirements::kUnconditionalRequirement) {
-            after = {};
-            changed = false;
-            return false;
-        }
-    }
-    return apply_material_requirements(
-        before,
-        std::span(definition.requirements)
-            .first(static_cast<std::size_t>(definition.requirementCount)),
-        after,
-        changed);
-}
-
-/** @return True when a pending profile acquisition carries canonical dense before/after images. */
-[[nodiscard]] bool
-valid_profile_mutation_shape(const PendingProfileItemAcquisition& mutation) noexcept {
-    if (!mutation.prepared || mutation.accountSoid == 0
-        || mutation.actionSource != (mutation.acquiredInstanceSoid != 0)
-        || mutation.acquiredDefinitionHash == authored_inventory::kNoDefinitionHash
-        || mutation.expectedItemCount > authored_inventory::kProfileItemCapacity
-        || mutation.afterItemCount > authored_inventory::kProfileItemCapacity
-        || mutation.profileIndex >= mutation.afterItemCount || mutation.previousQuantity < 0
-        || mutation.acquiredQuantity <= mutation.previousQuantity
-        || mutation.acquiredQuantity - mutation.previousQuantity != 1
-        || mutation.previousMutationSerial < 0
-        || mutation.acquiredMutationSerial <= mutation.previousMutationSerial) {
-        return false;
-    }
-    if (mutation.appended) {
-        if (mutation.afterItemCount == 0 || mutation.previousQuantity != 0) {
-            return false;
-        }
-    } else if (mutation.previousQuantity == 0) {
-        return false;
-    }
-
-    bool foundBeforeTarget = mutation.appended;
-    for (std::size_t index = 0; index < mutation.beforeItems.size(); ++index) {
-        const authored_inventory::ProfileItem& before = mutation.beforeItems[index];
-        const authored_inventory::ProfileItem& after = mutation.afterItems[index];
-        if (index < mutation.expectedItemCount
-            && before.mutationSerial >= mutation.acquiredMutationSerial) {
-            return false;
-        }
-        if (index >= mutation.expectedItemCount
-            && (before.instanceSoid != 0 || before.definitionHash != 0 || before.quantity != 0
-                || before.mutationSerial != 0)) {
-            return false;
-        }
-        if (index >= mutation.afterItemCount
-            && (after.instanceSoid != 0 || after.definitionHash != 0 || after.quantity != 0
-                || after.mutationSerial != 0)) {
-            return false;
-        }
-        if (!mutation.appended && index < mutation.expectedItemCount
-            && before.instanceSoid == mutation.acquiredInstanceSoid
-            && before.definitionHash == mutation.acquiredDefinitionHash
-            && before.quantity == mutation.previousQuantity
-            && before.mutationSerial == mutation.previousMutationSerial) {
-            if (foundBeforeTarget) {
-                return false;
-            }
-            foundBeforeTarget = true;
-        }
-    }
-    const authored_inventory::ProfileItem& acquired = mutation.afterItems[mutation.profileIndex];
-    return foundBeforeTarget && acquired.instanceSoid == mutation.acquiredInstanceSoid
-           && acquired.definitionHash == mutation.acquiredDefinitionHash
-           && acquired.quantity == mutation.acquiredQuantity
-           && acquired.mutationSerial == mutation.acquiredMutationSerial;
-}
-
-/** Applies one validated pending profile after-image over a current, matching account. */
-[[nodiscard]] bool materialize_profile_acquisition(const AccountState& current,
-                                                   const PendingProfileItemAcquisition& mutation,
-                                                   AccountState& after) noexcept {
-    if (!valid_profile_mutation_shape(mutation) || current.primarySoid != mutation.accountSoid
-        || !same_profile_inventory(current, mutation.beforeItems, mutation.expectedItemCount)) {
-        return false;
-    }
-    item_details::Definition detail{};
-    inventory_buckets::Descriptor bucket{};
-    build_data::items::Definition item{};
-    build_data::collectibles::Definition collectible{};
-    if (!build_data::find_collectible_definition(mutation.collectibleIndex, collectible)
-        || collectible.itemDefinitionIndex
-               == build_data::collectibles::kUnavailableItemDefinitionIndex
-        || collectible.materialRequirementSetHash != mutation.materialRequirementSetHash
-        || collectible.materialRequirementCount != mutation.materialRequirementCount
-        || !build_data::find_item_definition_hash(mutation.acquiredDefinitionHash, item)
-        || collectible.itemDefinitionIndex != item.definitionIndex
-        || !build_data::find_configured_item_detail(item.definitionIndex, detail)
-        || detail.definitionHash != mutation.acquiredDefinitionHash
-        || detail.definitionIndex != item.definitionIndex || detail.bucketId != item.bucketId
-        || detail.bucketId != mutation.bucketId
-        || detail.instancedDefinitionState != item_details::InstancedDefinitionState::stackable
-        || detail.maxStackSize <= 0 || mutation.acquiredQuantity > detail.maxStackSize
-        || !build_data::find_inventory_bucket_descriptor(detail.bucketId, bucket)
-        || bucket.arraySelector != inventory_buckets::ArraySelector::profile
-        || build_data::is_profile_action_source(item.definitionIndex, item.bucketId)
-               != mutation.actionSource) {
-        return false;
-    }
-    after = current;
-    after.profileItems = mutation.afterItems;
-    after.profileItemCount = mutation.afterItemCount;
-    return account::valid(after) && valid_profile_inventory(after);
-}
-
-/** Writes one exhaustive item-dismantle transaction checkpoint. */
-void report_dismantle(std::string_view stage,
-                      std::string_view result,
-                      std::string_view reason,
-                      std::uint32_t definitionHash,
-                      std::uint64_t characterSoid,
-                      std::uint64_t instanceSoid,
-                      std::size_t inventoryIndex,
-                      std::uint16_t inventoryRow,
-                      std::uint8_t equipmentSlot,
-                      std::size_t movedItemCount,
-                      std::uint32_t nextInventorySerial) noexcept {
-    std::array<char, core::log::kLineCapacity> line{};
-    const int count =
-        std::snprintf(line.data(),
-                      line.size(),
-                      "ev=dismantle stage=%.*s result=%.*s reason=%.*s definition_hash=0x%08X "
-                      "character=0x%llX instance=0x%llX inventory_index=%zu inventory_row=%u "
-                      "equipment_slot=%u moved_items=%zu next_serial=%u",
-                      static_cast<int>(stage.size()),
-                      stage.data(),
-                      static_cast<int>(result.size()),
-                      result.data(),
-                      static_cast<int>(reason.size()),
-                      reason.data(),
-                      definitionHash,
-                      static_cast<unsigned long long>(characterSoid),
-                      static_cast<unsigned long long>(instanceSoid),
-                      inventoryIndex,
-                      static_cast<unsigned>(inventoryRow),
-                      static_cast<unsigned>(equipmentSlot),
-                      movedItemCount,
-                      nextInventorySerial);
-    if (count > 0) {
-        core::log::write(core::log::Channel::state,
-                         result == "ok" ? core::log::Level::debug : core::log::Level::warn,
-                         {line.data(), static_cast<std::size_t>(count)});
-    }
-}
-
-/** Writes one bounded opcode-903 socket-selection transaction checkpoint. */
-void report_socket_plug(std::string_view stage,
-                        std::string_view result,
-                        std::string_view reason,
-                        std::uint64_t characterSoid,
-                        std::uint64_t targetInstanceSoid,
-                        std::uint16_t targetDefinitionIndex,
-                        std::uint8_t socketLane,
-                        std::uint16_t plugDefinitionIndex,
-                        std::uint8_t targetBucketId,
-                        std::uint8_t plugBucketId,
-                        bool targetEquipped,
-                        std::size_t itemIndex) noexcept {
-    std::array<char, core::log::kLineCapacity> line{};
-    const int count = std::snprintf(
-        line.data(),
-        line.size(),
-        "ev=socket_plug stage=%.*s result=%.*s reason=%.*s character=0x%llX "
-        "instance=0x%llX target_definition=%u target_bucket=%u lane=%u plug_definition=%u "
-        "plug_bucket=%u equipped=%u item_index=%zu",
-        static_cast<int>(stage.size()),
-        stage.data(),
-        static_cast<int>(result.size()),
-        result.data(),
-        static_cast<int>(reason.size()),
-        reason.data(),
-        static_cast<unsigned long long>(characterSoid),
-        static_cast<unsigned long long>(targetInstanceSoid),
-        static_cast<unsigned>(targetDefinitionIndex),
-        static_cast<unsigned>(targetBucketId),
-        static_cast<unsigned>(socketLane),
-        static_cast<unsigned>(plugDefinitionIndex),
-        static_cast<unsigned>(plugBucketId),
-        static_cast<unsigned>(targetEquipped),
-        itemIndex);
-    if (count > 0) {
-        core::log::write(core::log::Channel::state,
-                         result == "ok" ? core::log::Level::debug : core::log::Level::warn,
-                         {line.data(), static_cast<std::size_t>(count)});
-    }
-}
-
-/** Resolves the installed native equipment slot for one configured authored item. */
-[[nodiscard]] bool native_equipment_slot(const authored_inventory::Item& item,
-                                         std::uint8_t& slot) noexcept {
-    build_data::items::Definition definition{};
-    item_details::Definition detail{};
-    if (!build_data::find_item_definition_hash(item.definitionHash, definition)
-        || definition.definitionHash != item.definitionHash
-        || !build_data::find_configured_item_detail(definition.definitionIndex, detail)
-        || detail.definitionIndex != definition.definitionIndex
-        || detail.definitionHash != definition.definitionHash
-        || detail.bucketId != definition.bucketId || !detail.equipmentSlot.has_value()
-        || *detail.equipmentSlot < 0
-        || static_cast<std::size_t>(*detail.equipmentSlot) >= item_details::kEquipmentSlotCount) {
-        return false;
-    }
-    slot = static_cast<std::uint8_t>(*detail.equipmentSlot);
-    return true;
-}
-
-/** Resolves the installed physical inventory bucket for one configured authored item. */
-[[nodiscard]] bool inventory_bucket_id(const authored_inventory::Item& item,
-                                       std::uint8_t& bucketId) noexcept {
-    build_data::items::Definition definition{};
-    item_details::Definition detail{};
-    if (!build_data::find_item_definition_hash(item.definitionHash, definition)
-        || definition.definitionHash != item.definitionHash
-        || !build_data::find_configured_item_detail(definition.definitionIndex, detail)
-        || detail.definitionIndex != definition.definitionIndex
-        || detail.definitionHash != definition.definitionHash
-        || detail.bucketId != definition.bucketId) {
-        return false;
-    }
-    bucketId = detail.bucketId;
-    return true;
-}
-
-/** Maps the 16 proven native equipment positions onto their stable authored State slots. */
-[[nodiscard]] bool semantic_equipment_slot(std::uint8_t nativeSlot,
-                                           std::size_t& semanticIndex) noexcept {
-    using EquipmentSlot = authored_inventory::EquipmentSlot;
-    EquipmentSlot semanticSlot = EquipmentSlot::count;
-    switch (nativeSlot) {
-    case 0:
-        semanticSlot = EquipmentSlot::subclass;
-        break;
-    case 1:
-        semanticSlot = EquipmentSlot::helmet;
-        break;
-    case 2:
-        semanticSlot = EquipmentSlot::gauntlets;
-        break;
-    case 4:
-        semanticSlot = EquipmentSlot::chest;
-        break;
-    case 5:
-        semanticSlot = EquipmentSlot::legs;
-        break;
-    case 6:
-        semanticSlot = EquipmentSlot::classItem;
-        break;
-    case 7:
-        semanticSlot = EquipmentSlot::kinetic;
-        break;
-    case 8:
-        semanticSlot = EquipmentSlot::energy;
-        break;
-    case 9:
-        semanticSlot = EquipmentSlot::heavy;
-        break;
-    case 10:
-        semanticSlot = EquipmentSlot::ship;
-        break;
-    case 11:
-        semanticSlot = EquipmentSlot::vehicle;
-        break;
-    case 12:
-        semanticSlot = EquipmentSlot::ghost;
-        break;
-    case 13:
-        semanticSlot = EquipmentSlot::emblem;
-        break;
-    case 14:
-        semanticSlot = EquipmentSlot::emote;
-        break;
-    case 15:
-        semanticSlot = EquipmentSlot::clanBanner;
-        break;
-    case 17:
-        semanticSlot = EquipmentSlot::finisher;
-        break;
-    default:
-        return false;
-    }
-    semanticIndex = static_cast<std::size_t>(semanticSlot);
-    return semanticIndex < authored_inventory::kEquipmentSlotCount;
-}
-
-/** Finds one instance exactly once in a checked, row-sorted loadout. */
-[[nodiscard]] bool find_resolved_position(const family4_loadout::ResolvedLoadout& loadout,
-                                          std::uint64_t instanceSoid,
-                                          ResolvedPosition& position) noexcept {
-    bool found = false;
-    for (std::size_t index = 0; index < loadout.itemCount; ++index) {
-        const family4_loadout::ResolvedItem& item = loadout.items[index];
-        if (item.instance.instanceSoid != instanceSoid) {
-            continue;
-        }
-        if (found) {
-            return false;
-        }
-        found = true;
-        position.inventoryRow = item.inventoryRow;
-        position.equipmentSlot = item.equipmentSlot;
-        position.equipped = item.equipped;
-        position.mutationSerial = item.mutationSerial;
-    }
-    return found;
-}
-
-/** @return True when the native placement and equipped marker are unchanged. */
-[[nodiscard]] bool same_position(const ResolvedPosition& left,
-                                 const ResolvedPosition& right) noexcept {
-    return left.inventoryRow == right.inventoryRow && left.equipmentSlot == right.equipmentSlot
-           && left.equipped == right.equipped;
-}
-
-/**
- * Applies canonical mutation generations after one shape-only equipment transition.
- *
- * Every surviving instance must preserve its native bucket. A generation advances exactly when
- * its published native row or equipped marker changes, and a second resolution proves that the
- * stamped after-image retained the staged placement.
- */
-[[nodiscard]] bool
-finalize_equipment_transition(const AccountState& account,
-                              std::size_t characterIndex,
-                              std::uint64_t requestedInstanceSoid,
-                              EquipmentMutationKind kind,
-                              std::uint8_t expectedNativeSlot,
-                              const family4_loadout::ResolvedLoadout& beforeLoadout,
-                              CharacterState& after,
-                              std::size_t& movedItemCount) noexcept {
-    movedItemCount = 0;
-    if (characterIndex >= account.characterCount || kind == EquipmentMutationKind::none) {
-        return false;
-    }
-
-    AccountState candidate = account;
-    candidate.characters[characterIndex] = after;
-    family4_loadout::ResolvedLoadout placedAfter{};
-    if (!account::valid(candidate)
-        || !family4_loadout::resolve(candidate, characterIndex, placedAfter)
-        || placedAfter.itemCount != beforeLoadout.itemCount) {
-        return false;
-    }
-
-    ResolvedPosition beforeRequested{};
-    ResolvedPosition afterRequested{};
-    if (!find_resolved_position(beforeLoadout, requestedInstanceSoid, beforeRequested)
-        || !find_resolved_position(placedAfter, requestedInstanceSoid, afterRequested)
-        || beforeRequested.equipmentSlot != expectedNativeSlot
-        || afterRequested.equipmentSlot != expectedNativeSlot
-        || (kind == EquipmentMutationKind::equip
-            && (beforeRequested.equipped || !afterRequested.equipped))
-        || (kind == EquipmentMutationKind::unequip
-            && (!beforeRequested.equipped || afterRequested.equipped))) {
-        return false;
-    }
-
-    const auto count_move = [&](const authored_inventory::Item& item) noexcept {
-        ResolvedPosition beforePosition{};
-        ResolvedPosition afterPosition{};
-        if (!find_resolved_position(beforeLoadout, item.instanceSoid, beforePosition)
-            || !find_resolved_position(placedAfter, item.instanceSoid, afterPosition)
-            || beforePosition.equipmentSlot != afterPosition.equipmentSlot) {
-            return false;
-        }
-        movedItemCount += static_cast<std::size_t>(!same_position(beforePosition, afterPosition));
-        return true;
-    };
-    for (const auto& item : after.equipment.slots) {
-        if (item.has_value() && !count_move(*item)) {
-            return false;
-        }
-    }
-    for (std::size_t index = 0; index < after.inventory.count; ++index) {
-        if (!count_move(after.inventory.values[index])) {
-            return false;
-        }
-    }
-
-    // The serial is signed on the wire, so it must stay inside the positive int32 range.
-    constexpr std::uint32_t kMaximumInventorySerial =
-        static_cast<std::uint32_t>((std::numeric_limits<std::int32_t>::max)());
-    if (movedItemCount == 0 || after.nextInventorySerial > kMaximumInventorySerial
-        || movedItemCount > kMaximumInventorySerial - after.nextInventorySerial) {
-        return false;
-    }
-
-    const auto stamp_move = [&](authored_inventory::Item& item) noexcept {
-        ResolvedPosition beforePosition{};
-        ResolvedPosition afterPosition{};
-        if (!find_resolved_position(beforeLoadout, item.instanceSoid, beforePosition)
-            || !find_resolved_position(placedAfter, item.instanceSoid, afterPosition)
-            || beforePosition.equipmentSlot != afterPosition.equipmentSlot) {
-            return false;
-        }
-        if (!same_position(beforePosition, afterPosition)) {
-            item.mutationSerial = static_cast<std::int32_t>(after.nextInventorySerial++);
-        }
-        return true;
-    };
-    for (auto& item : after.equipment.slots) {
-        if (item.has_value() && !stamp_move(*item)) {
-            return false;
-        }
-    }
-    for (std::size_t index = 0; index < after.inventory.count; ++index) {
-        if (!stamp_move(after.inventory.values[index])) {
-            return false;
-        }
-    }
-
-    candidate.characters[characterIndex] = after;
-    family4_loadout::ResolvedLoadout checkedAfter{};
-    if (!account::valid(candidate)
-        || !family4_loadout::resolve(candidate, characterIndex, checkedAfter)
-        || checkedAfter.itemCount != placedAfter.itemCount) {
-        return false;
-    }
-    for (const auto& item : after.equipment.slots) {
-        if (!item.has_value()) {
-            continue;
-        }
-        ResolvedPosition placed{};
-        ResolvedPosition checked{};
-        if (!find_resolved_position(placedAfter, item->instanceSoid, placed)
-            || !find_resolved_position(checkedAfter, item->instanceSoid, checked)
-            || !same_position(placed, checked) || checked.mutationSerial != item->mutationSerial) {
-            return false;
-        }
-    }
-    for (std::size_t index = 0; index < after.inventory.count; ++index) {
-        const authored_inventory::Item& item = after.inventory.values[index];
-        ResolvedPosition placed{};
-        ResolvedPosition checked{};
-        if (!find_resolved_position(placedAfter, item.instanceSoid, placed)
-            || !find_resolved_position(checkedAfter, item.instanceSoid, checked)
-            || !same_position(placed, checked) || checked.mutationSerial != item.mutationSerial) {
-            return false;
-        }
-    }
-    return true;
-}
-
-/** @return True when two authored item values are identical, including socket policy and tail. */
-[[nodiscard]] bool same_item(const authored_inventory::Item& left,
-                             const authored_inventory::Item& right) noexcept {
-    return left.instanceSoid == right.instanceSoid && left.definitionHash == right.definitionHash
-           && left.level == right.level && left.quantity == right.quantity
-           && left.flags == right.flags && left.sockets.policy == right.sockets.policy
-           && left.sockets.plugCount == right.sockets.plugCount
-           && left.sockets.plugs == right.sockets.plugs;
-}
-
-/** Records one checked native item-state transition. */
-void report_item_state(std::string_view stage,
-                       std::string_view result,
-                       std::string_view reason,
-                       std::uint64_t characterSoid,
-                       std::uint64_t instanceSoid,
-                       std::uint16_t definitionIndex,
-                       std::uint32_t beforeFlags,
-                       std::uint32_t afterFlags,
-                       bool equipped,
-                       std::size_t itemIndex) noexcept {
-    std::array<char, core::log::kLineCapacity> line{};
-    const int count = std::snprintf(
-        line.data(),
-        line.size(),
-        "ev=item_state stage=%.*s result=%.*s reason=%.*s character=0x%llX instance=0x%llX "
-        "definition=%u flags_before=0x%X flags_after=0x%X equipped=%u item_index=%zu",
-        static_cast<int>(stage.size()),
-        stage.data(),
-        static_cast<int>(result.size()),
-        result.data(),
-        static_cast<int>(reason.size()),
-        reason.data(),
-        static_cast<unsigned long long>(characterSoid),
-        static_cast<unsigned long long>(instanceSoid),
-        static_cast<unsigned>(definitionIndex),
-        beforeFlags,
-        afterFlags,
-        equipped ? 1U : 0U,
-        itemIndex);
-    if (count > 0) {
-        core::log::write(core::log::Channel::state,
-                         result == "ok" ? core::log::Level::debug : core::log::Level::warn,
-                         {line.data(), static_cast<std::size_t>(count)});
-    }
-}
-
-/** Exact stationary-item comparison, including its inventory mutation generation. */
-[[nodiscard]] bool same_stationary_item(const authored_inventory::Item& left,
-                                        const authored_inventory::Item& right) noexcept {
-    return same_item(left, right) && left.mutationSerial == right.mutationSerial;
-}
-
-/** @return True when every item-bearing field of two character views is identical. */
-[[nodiscard]] bool same_loadout(const CharacterState& left, const CharacterState& right) noexcept {
-    if (left.soid != right.soid || left.selected != right.selected || left.race != right.race
-        || left.gender != right.gender || left.characterClass != right.characterClass
-        || left.level != right.level || left.accepted != right.accepted
-        || left.previewAvailable != right.previewAvailable
-        || left.appearanceValue != right.appearanceValue
-        || left.lastOrbitedDestination != right.lastOrbitedDestination
-        || left.contentBypass != right.contentBypass
-        || left.movementAbilityEntry != right.movementAbilityEntry
-        || left.grenadeAbilityEntry != right.grenadeAbilityEntry
-        || left.superAbilityEntry != right.superAbilityEntry
-        || left.meleeAbilityEntry != right.meleeAbilityEntry
-        || left.classAbilityEntry != right.classAbilityEntry
-        || left.nextInventorySerial != right.nextInventorySerial
-        || left.inventory.count != right.inventory.count) {
-        return false;
-    }
-    for (std::size_t index = 0; index < left.equipment.slots.size(); ++index) {
-        const auto& leftItem = left.equipment.slots[index];
-        const auto& rightItem = right.equipment.slots[index];
-        if (leftItem.has_value() != rightItem.has_value()
-            || (leftItem.has_value() && !same_stationary_item(*leftItem, *rightItem))) {
-            return false;
-        }
-    }
-    for (std::size_t index = 0; index < left.inventory.count; ++index) {
-        if (!same_stationary_item(left.inventory.values[index], right.inventory.values[index])) {
-            return false;
-        }
-    }
-    return true;
-}
-
-/** Exact character comparison, including the canonical unused inventory tail. */
-[[nodiscard]] bool same_character(const CharacterState& left,
-                                  const CharacterState& right) noexcept {
-    if (!same_loadout(left, right)) {
-        return false;
-    }
-    for (std::size_t index = left.inventory.count; index < left.inventory.values.size(); ++index) {
-        if (!same_stationary_item(left.inventory.values[index], right.inventory.values[index])) {
-            return false;
-        }
-    }
-    return true;
-}
-
-/** Stable location of one character-owned item inside authored State. */
-struct CharacterItemLocation {
-    std::size_t index{};
-    bool equipped{};
-};
-
-/** Finds one item SOID exactly once in the character's equipment and dense inventory. */
-[[nodiscard]] bool find_character_item_location(const CharacterState& character,
-                                                std::uint64_t instanceSoid,
-                                                CharacterItemLocation& location) noexcept {
-    location = {};
-    bool found = false;
-    for (std::size_t index = 0; index < character.equipment.slots.size(); ++index) {
-        const auto& item = character.equipment.slots[index];
-        if (!item.has_value() || item->instanceSoid != instanceSoid) {
-            continue;
-        }
-        if (found) {
-            return false;
-        }
-        found = true;
-        location = {index, true};
-    }
-    for (std::size_t index = 0; index < character.inventory.count; ++index) {
-        if (character.inventory.values[index].instanceSoid != instanceSoid) {
-            continue;
-        }
-        if (found) {
-            return false;
-        }
-        found = true;
-        location = {index, false};
-    }
-    return found;
-}
-
-/** Borrows an item at a previously validated authored location. */
-[[nodiscard]] const authored_inventory::Item*
-character_item_at(const CharacterState& character, const CharacterItemLocation& location) noexcept {
-    if (location.equipped) {
-        if (location.index >= character.equipment.slots.size()
-            || !character.equipment.slots[location.index].has_value()) {
-            return nullptr;
-        }
-        return &*character.equipment.slots[location.index];
-    }
-    if (location.index >= character.inventory.count) {
-        return nullptr;
-    }
-    return &character.inventory.values[location.index];
-}
-
-/** Borrows a mutable item at a previously validated authored location. */
-[[nodiscard]] authored_inventory::Item*
-character_item_at(CharacterState& character, const CharacterItemLocation& location) noexcept {
-    if (location.equipped) {
-        if (location.index >= character.equipment.slots.size()
-            || !character.equipment.slots[location.index].has_value()) {
-            return nullptr;
-        }
-        return &*character.equipment.slots[location.index];
-    }
-    if (location.index >= character.inventory.count) {
-        return nullptr;
-    }
-    return &character.inventory.values[location.index];
-}
-
-/** Materializes native initial plugs as a complete authored socket block. */
-[[nodiscard]] bool materialize_native_sockets(const item_details::Definition& detail,
-                                              authored_inventory::Sockets& sockets) noexcept {
-    sockets = {};
-    if (detail.ordinarySocketState != item_details::OrdinarySocketState::present
-        || detail.ordinarySocketCount > sockets.plugs.size()) {
-        return false;
-    }
-    sockets.policy = authored_inventory::SocketPolicy::authored;
-    sockets.plugCount = detail.ordinarySocketCount;
-    for (std::size_t lane = 0; lane < sockets.plugCount; ++lane) {
-        const std::uint16_t plugIndex = detail.initialPlugIndices[lane];
-        if (plugIndex == item_details::kUnavailableItemIndex) {
-            continue;
-        }
-        build_data::items::Definition plug{};
-        if (!build_data::find_item_definition_index(plugIndex, plug)
-            || plug.definitionIndex != plugIndex
-            || plug.definitionHash == authored_inventory::kNoDefinitionHash) {
-            return false;
-        }
-        sockets.plugs[lane] = plug.definitionHash;
-    }
-    return authored_inventory::valid(sockets);
-}
-
-/** Stages the canonical socket-only after-image over one already validated account snapshot. */
-[[nodiscard]] bool stage_socket_plug(const AccountState& snapshot,
-                                     std::size_t characterIndex,
-                                     std::uint64_t targetInstanceSoid,
-                                     std::uint8_t socketLane,
-                                     std::uint16_t plugDefinitionIndex,
-                                     PendingSocketPlug& mutation) noexcept {
-    mutation = {};
-    CharacterItemLocation location{};
-    build_data::items::Definition targetDefinition{};
-    build_data::items::Definition plugDefinition{};
-    const auto fail = [&](std::string_view reason) noexcept {
-        const std::uint64_t characterSoid =
-            characterIndex < snapshot.characterCount ? snapshot.characters[characterIndex].soid : 0;
-        report_socket_plug("stage_internal",
-                           "fail",
-                           reason,
-                           characterSoid,
-                           targetInstanceSoid,
-                           targetDefinition.definitionIndex,
-                           socketLane,
-                           plugDefinitionIndex,
-                           targetDefinition.bucketId,
-                           plugDefinition.bucketId,
-                           location.equipped,
-                           location.index);
-        mutation = {};
-        return false;
-    };
-    if (!account::valid(snapshot) || characterIndex >= snapshot.characterCount
-        || targetInstanceSoid == 0 || socketLane >= authored_inventory::kPlugCapacity) {
-        return fail("request_or_account");
-    }
-    const CharacterState& before = snapshot.characters[characterIndex];
-    if (!before.selected || before.soid == 0) {
-        return fail("selected_character");
-    }
-
-    family4_loadout::ResolvedLoadout beforeLoadout{};
-    if (!find_character_item_location(before, targetInstanceSoid, location)
-        || !family4_loadout::resolve(snapshot, characterIndex, beforeLoadout)) {
-        return fail("target_or_before_loadout");
-    }
-    const authored_inventory::Item* target = character_item_at(before, location);
-    item_details::Definition detail{};
-    if (target == nullptr
-        || !build_data::find_item_definition_hash(target->definitionHash, targetDefinition)
-        || targetDefinition.definitionHash != target->definitionHash
-        || !build_data::find_configured_item_detail(targetDefinition.definitionIndex, detail)
-        || detail.definitionIndex != targetDefinition.definitionIndex
-        || detail.definitionHash != targetDefinition.definitionHash
-        || detail.bucketId != targetDefinition.bucketId
-        || detail.ordinarySocketState != item_details::OrdinarySocketState::present
-        || socketLane >= detail.ordinarySocketCount
-        || detail.ordinarySocketCount > authored_inventory::kPlugCapacity
-        || !build_data::find_item_definition_index(plugDefinitionIndex, plugDefinition)
-        || plugDefinition.definitionIndex != plugDefinitionIndex
-        || plugDefinition.definitionHash == authored_inventory::kNoDefinitionHash
-        || !build_data::is_socket_plug_allowed(
-            targetDefinition.definitionIndex, socketLane, plugDefinitionIndex)) {
-        return fail("definition_or_compatibility");
-    }
-
-    // Ownership is only meaningful where the plug is a finite supply the account draws down. A
-    // shader is one: it is pulled from Collections into a profile stack and spent by applying it.
-    // An ornament is a permanent unlock the account holds once earned, not a stack it draws
-    // down, which is why the Client offers every valid one for a socket. Requiring a stack for
-    // one would refuse a plug the account already has.
-    const bool consumesStack =
-        build_data::is_profile_action_source(plugDefinitionIndex, plugDefinition.bucketId)
-        && build_data::is_consumed_on_apply(plugDefinitionIndex, plugDefinition.bucketId)
-        && !(socketLane < detail.initialPlugIndices.size()
-             && detail.initialPlugIndices[socketLane] == plugDefinitionIndex);
-    if (consumesStack && !holds_plug_source(snapshot, plugDefinition.definitionHash)) {
-        return fail("plug_ownership");
-    }
-
-    AccountState chargedAccount = snapshot;
-    build_data::material_requirements::Definition materialSet{};
-    bool profileChanged = false;
-    const std::uint16_t materialSetIndex = plugDefinition.insertionMaterialRequirementSetIndex;
-    if (materialSetIndex != build_data::items::kUnavailableMaterialRequirementSetIndex
-        && (!build_data::find_material_requirement_set(materialSetIndex, materialSet)
-            || materialSet.requirementSetIndex != materialSetIndex
-            || !apply_action_materials(snapshot, materialSet, chargedAccount, profileChanged))) {
-        return fail("materials");
-    }
-
-    // Applying spends the stack the plug came from. The insertion cost above is a separate
-    // authored charge that leaves the plug itself untouched, so the unit is taken here.
-    //
-    // The authored-cost path cannot do this. It refuses any row carrying an instance key, because
-    // it exists for the non-instanced currency and material stacks, and an action source always
-    // carries one. Spending one is therefore its own transition: the row keeps its identity while
-    // any unit remains, and releases it with the row once the last unit goes.
-    if (consumesStack && !spend_plug_source(chargedAccount, plugDefinition.definitionHash)) {
-        return fail("plug_stack");
-    }
-    profileChanged = profileChanged || consumesStack;
-
-    authored_inventory::Sockets authoredSockets{};
-    if (target->sockets.policy == authored_inventory::SocketPolicy::nativeDefaults) {
-        if (!materialize_native_sockets(detail, authoredSockets)) {
-            return fail("native_sockets");
-        }
-    } else {
-        authoredSockets = target->sockets;
-        if (authoredSockets.policy != authored_inventory::SocketPolicy::authored
-            || authoredSockets.plugCount != detail.ordinarySocketCount
-            || !authored_inventory::valid(authoredSockets)) {
-            return fail("authored_sockets");
-        }
-    }
-    if (authoredSockets.plugs[socketLane].has_value()
-        && *authoredSockets.plugs[socketLane] == plugDefinition.definitionHash) {
-        return fail("already_applied");
-    }
-    authoredSockets.plugs[socketLane] = plugDefinition.definitionHash;
-
-    CharacterState after = before;
-    authored_inventory::Item* changed = character_item_at(after, location);
-    if (changed == nullptr || changed->instanceSoid != target->instanceSoid
-        || changed->definitionHash != target->definitionHash || changed->level != target->level
-        || changed->quantity != target->quantity
-        || changed->mutationSerial != target->mutationSerial) {
-        return fail("target_copy");
-    }
-    changed->sockets = authoredSockets;
-
-    AccountState candidate = chargedAccount;
-    candidate.characters[characterIndex] = after;
-    family4_loadout::ResolvedLoadout afterLoadout{};
-    ResolvedPosition beforePosition{};
-    ResolvedPosition afterPosition{};
-    const family4_loadout::ResolvedItem* resolvedTarget = nullptr;
-    for (std::size_t index = 0; index < beforeLoadout.itemCount; ++index) {
-        const auto& resolved = beforeLoadout.items[index];
-        if (resolved.instance.instanceSoid == targetInstanceSoid
-            && resolved.instance.baseDefinitionIndex != targetDefinition.definitionIndex) {
-            return fail("before_definition");
-        }
-    }
-    if (!account::valid(candidate)
-        || !family4_loadout::resolve(candidate, characterIndex, afterLoadout)
-        || !find_resolved_position(beforeLoadout, targetInstanceSoid, beforePosition)
-        || !find_resolved_position(afterLoadout, targetInstanceSoid, afterPosition)
-        || !same_position(beforePosition, afterPosition)) {
-        return fail("candidate_or_position");
-    }
-    for (std::size_t index = 0; index < afterLoadout.itemCount; ++index) {
-        const auto& resolved = afterLoadout.items[index];
-        if (resolved.instance.instanceSoid != targetInstanceSoid) {
-            continue;
-        }
-        if (resolvedTarget != nullptr) {
-            return fail("duplicate_target");
-        }
-        resolvedTarget = &resolved;
-    }
-    if (resolvedTarget == nullptr
-        || resolvedTarget->instance.baseDefinitionIndex != targetDefinition.definitionIndex
-        || resolvedTarget->instance.ordinarySockets.state
-               != middleware::datagen::family4::instance::OrdinarySocketBlockState::present
-        || !resolvedTarget->instance.ordinarySockets.plugs[socketLane].has_value()
-        || *resolvedTarget->instance.ordinarySockets.plugs[socketLane] != plugDefinitionIndex) {
-        return fail("after_socket");
-    }
-
-    mutation.beforeCharacter = before;
-    mutation.afterCharacter = after;
-    mutation.beforeProfileItems = snapshot.profileItems;
-    mutation.afterProfileItems = chargedAccount.profileItems;
-    mutation.accountSoid = snapshot.primarySoid;
-    mutation.characterSoid = before.soid;
-    mutation.targetInstanceSoid = targetInstanceSoid;
-    mutation.targetDefinitionHash = targetDefinition.definitionHash;
-    mutation.plugDefinitionHash = plugDefinition.definitionHash;
-    mutation.materialRequirementSetHash = materialSet.requirementSetHash;
-    mutation.characterIndex = characterIndex;
-    mutation.expectedProfileItemCount = snapshot.profileItemCount;
-    mutation.afterProfileItemCount = chargedAccount.profileItemCount;
-    mutation.itemIndex = location.index;
-    mutation.targetDefinitionIndex = targetDefinition.definitionIndex;
-    mutation.plugDefinitionIndex = plugDefinitionIndex;
-    mutation.materialRequirementSetIndex = materialSetIndex;
-    mutation.socketLane = socketLane;
-    mutation.targetBucketId = targetDefinition.bucketId;
-    mutation.plugBucketId = plugDefinition.bucketId;
-    mutation.materialRequirementCount = materialSet.requirementCount;
-    mutation.profileChanged = profileChanged;
-    mutation.targetEquipped = location.equipped;
-    mutation.prepared = true;
-    return true;
-}
-
-/** Stages one complete accumulated item-state value without moving or recreating the item. */
-[[nodiscard]] bool stage_item_state(const AccountState& snapshot,
-                                    std::size_t characterIndex,
-                                    std::uint64_t targetInstanceSoid,
-                                    std::uint16_t targetDefinitionIndex,
-                                    std::uint32_t flags,
-                                    PendingItemState& mutation) noexcept {
-    mutation = {};
-    // Bits 0 and 1 are the two states the client sends. Any other bit is a request we cannot
-    // honour.
-    constexpr std::uint32_t kSupportedItemStateMask = 0x3U;
-    if (!account::valid(snapshot) || characterIndex >= snapshot.characterCount
-        || targetInstanceSoid == 0 || (flags & ~kSupportedItemStateMask) != 0) {
-        return false;
-    }
-    const CharacterState& before = snapshot.characters[characterIndex];
-    if (!before.selected || before.soid == 0) {
-        return false;
-    }
-
-    CharacterItemLocation location{};
-    family4_loadout::ResolvedLoadout beforeLoadout{};
-    if (!find_character_item_location(before, targetInstanceSoid, location)
-        || !family4_loadout::resolve(snapshot, characterIndex, beforeLoadout)) {
-        return false;
-    }
-    const authored_inventory::Item* target = character_item_at(before, location);
-    build_data::items::Definition definition{};
-    ResolvedPosition beforePosition{};
-    if (target == nullptr || target->flags == flags
-        || !build_data::find_item_definition_hash(target->definitionHash, definition)
-        || definition.definitionHash != target->definitionHash
-        || definition.definitionIndex != targetDefinitionIndex
-        || !find_resolved_position(beforeLoadout, targetInstanceSoid, beforePosition)) {
-        return false;
-    }
-
-    CharacterState after = before;
-    authored_inventory::Item* changed = character_item_at(after, location);
-    if (changed == nullptr || !same_stationary_item(*changed, *target)) {
-        return false;
-    }
-    changed->flags = flags;
-
-    AccountState candidate = snapshot;
-    candidate.characters[characterIndex] = after;
-    family4_loadout::ResolvedLoadout afterLoadout{};
-    ResolvedPosition afterPosition{};
-    if (!account::valid(candidate)
-        || !family4_loadout::resolve(candidate, characterIndex, afterLoadout)
-        || !find_resolved_position(afterLoadout, targetInstanceSoid, afterPosition)
-        || !same_position(beforePosition, afterPosition)) {
-        return false;
-    }
-
-    mutation.beforeCharacter = before;
-    mutation.afterCharacter = after;
-    mutation.characterSoid = before.soid;
-    mutation.targetInstanceSoid = targetInstanceSoid;
-    mutation.characterIndex = characterIndex;
-    mutation.itemIndex = location.index;
-    mutation.targetDefinitionIndex = targetDefinitionIndex;
-    mutation.beforeFlags = target->flags;
-    mutation.afterFlags = flags;
-    mutation.targetEquipped = location.equipped;
-    mutation.prepared = true;
-    return true;
-}
-
-/** Returns one character-owned instance's definition hash for bounded transaction diagnostics. */
-[[nodiscard]] std::uint32_t character_item_definition_hash(const CharacterState& character,
-                                                           std::uint64_t instanceSoid) noexcept {
-    for (const auto& item : character.equipment.slots) {
-        if (item.has_value() && item->instanceSoid == instanceSoid) {
-            return item->definitionHash;
-        }
-    }
-    for (std::size_t index = 0; index < character.inventory.count; ++index) {
-        if (character.inventory.values[index].instanceSoid == instanceSoid) {
-            return character.inventory.values[index].definitionHash;
-        }
-    }
-    return 0;
-}
-
-/** @return True when any account, character, profile-stack, or character-item key owns one SOID. */
-[[nodiscard]] bool account_owns_soid(const AccountState& account, std::uint64_t soid) noexcept {
-    if (soid == 0 || account.primarySoid == soid) {
-        return true;
-    }
-    for (std::size_t index = 0; index < account.profileItemCount; ++index) {
-        if (account.profileItems[index].instanceSoid == soid) {
-            return true;
-        }
-    }
-    for (std::size_t characterIndex = 0; characterIndex < account.characterCount;
-         ++characterIndex) {
-        const CharacterState& character = account.characters[characterIndex];
-        if (character.soid == soid) {
-            return true;
-        }
-        for (const auto& item : character.equipment.slots) {
-            if (item.has_value() && item->instanceSoid == soid) {
-                return true;
-            }
-        }
-        for (std::size_t index = 0; index < character.inventory.count; ++index) {
-            if (character.inventory.values[index].instanceSoid == soid) {
-                return true;
-            }
-        }
-    }
-    return false;
-}
-
-/** Finds a fresh deterministic item-instance SOID without sharing any other identity key. */
-[[nodiscard]] bool next_item_instance_soid(const AccountState& account,
-                                           std::uint64_t& output) noexcept {
-    std::uint64_t candidate = kFirstGeneratedItemSoid;
-    for (std::size_t characterIndex = 0; characterIndex < account.characterCount;
-         ++characterIndex) {
-        const CharacterState& character = account.characters[characterIndex];
-        for (const auto& item : character.equipment.slots) {
-            if (!item.has_value() || item->instanceSoid < candidate) {
-                continue;
-            }
-            if (item->instanceSoid == (std::numeric_limits<std::uint64_t>::max)()) {
-                return false;
-            }
-            candidate = item->instanceSoid + 1U;
-        }
-        for (std::size_t index = 0; index < character.inventory.count; ++index) {
-            const std::uint64_t instanceSoid = character.inventory.values[index].instanceSoid;
-            if (instanceSoid < candidate) {
-                continue;
-            }
-            if (instanceSoid == (std::numeric_limits<std::uint64_t>::max)()) {
-                return false;
-            }
-            candidate = instanceSoid + 1U;
-        }
-    }
-    while (account_owns_soid(account, candidate)) {
-        if (candidate == (std::numeric_limits<std::uint64_t>::max)()) {
-            return false;
-        }
-        ++candidate;
-    }
-    output = candidate;
-    return output != 0;
-}
-
-/** Finds a collision-free SOID for one newly appended profile stack. */
-[[nodiscard]] bool next_profile_item_instance_soid(const AccountState& account,
-                                                   std::uint64_t& output) noexcept {
-    std::uint64_t candidate = authored_inventory::kFirstProfileItemInstanceSoid;
-    while (account_owns_soid(account, candidate)) {
-        if (candidate == (std::numeric_limits<std::uint64_t>::max)()) {
-            return false;
-        }
-        ++candidate;
-    }
-    output = candidate;
-    return output != 0;
-}
-
-/** @return True when an account or character identity already owns the candidate object key. */
-[[nodiscard]] bool identity_uses_soid(const AccountState& account, std::uint64_t soid) noexcept {
-    if (soid == 0 || account.primarySoid == soid) {
-        return true;
-    }
-    for (std::size_t index = 0; index < account.characterCount; ++index) {
-        if (account.characters[index].soid == soid) {
-            return true;
-        }
-    }
-    return false;
-}
-
-/** Uses the character's strongest existing item as the neutral local Collections pull level. */
-[[nodiscard]] std::int32_t acquisition_level(const CharacterState& character) noexcept {
-    std::int32_t level = 0;
-    for (const auto& item : character.equipment.slots) {
-        if (item.has_value()) {
-            level = (std::max)(level, item->level);
-        }
-    }
-    for (std::size_t index = 0; index < character.inventory.count; ++index) {
-        level = (std::max)(level, character.inventory.values[index].level);
-    }
-    return level;
-}
-
-/** Finds the one resolved unequipped row created by an acquisition candidate. */
-[[nodiscard]] bool find_acquired_row(const family4_loadout::ResolvedLoadout& loadout,
-                                     std::uint64_t instanceSoid,
-                                     std::uint16_t& inventoryRow,
-                                     std::uint8_t& equipmentSlot) noexcept {
-    bool found = false;
-    for (std::size_t index = 0; index < loadout.itemCount; ++index) {
-        const family4_loadout::ResolvedItem& item = loadout.items[index];
-        if (item.instance.instanceSoid != instanceSoid) {
-            continue;
-        }
-        if (found || item.equipped) {
-            return false;
-        }
-        found = true;
-        inventoryRow = item.inventoryRow;
-        equipmentSlot = item.equipmentSlot;
-    }
-    return found;
-}
-
-/** Finds the unique resolved unequipped position for one instance. */
-[[nodiscard]] bool find_unequipped_row(const family4_loadout::ResolvedLoadout& loadout,
-                                       std::uint64_t instanceSoid,
-                                       std::uint16_t& inventoryRow,
-                                       std::uint8_t& equipmentSlot) noexcept {
-    bool found = false;
-    for (std::size_t index = 0; index < loadout.itemCount; ++index) {
-        const family4_loadout::ResolvedItem& item = loadout.items[index];
-        if (item.instance.instanceSoid != instanceSoid) {
-            continue;
-        }
-        if (found || item.equipped) {
-            return false;
-        }
-        found = true;
-        inventoryRow = item.inventoryRow;
-        equipmentSlot = item.equipmentSlot;
-    }
-    return found;
-}
-
-/** @return True when the resolved loadout still carries an instance with this key. */
-[[nodiscard]] bool loadout_contains(const family4_loadout::ResolvedLoadout& loadout,
-                                    std::uint64_t instanceSoid) noexcept {
-    for (std::size_t index = 0; index < loadout.itemCount; ++index) {
-        if (loadout.items[index].instance.instanceSoid == instanceSoid) {
-            return true;
-        }
-    }
-    return false;
-}
-
-/**
- * Credits the supported client's ordinary weapon/armor dismantle payout.
- *
- * Capped stacks
- * lose only the overflowing part, matching normal profile-inventory behavior.
- * Every credited row
- * receives a new mutation serial so the account observer can display it.
- */
-[[nodiscard]] bool
-apply_dismantle_rewards(const AccountState& before,
-                        std::uint8_t equipmentSlot,
-                        AccountState& after,
-                        std::array<DismantleReward, kDismantleRewardCapacity>& rewards,
-                        std::size_t& rewardCount) noexcept {
-    after = before;
-    rewards = {};
-    rewardCount = 0;
-    if (!valid_profile_inventory(before)) {
-        return false;
-    }
-    if (equipmentSlot >= kGearEquipmentSlotCount) {
-        return true;
-    }
-
-    std::int32_t greatestMutationSerial = 0;
-    for (std::size_t index = 0; index < before.profileItemCount; ++index) {
-        greatestMutationSerial =
-            (std::max)(greatestMutationSerial, before.profileItems[index].mutationSerial);
-    }
-
-    for (std::size_t policyIndex = 0; policyIndex < before.dismantleRewardCount; ++policyIndex) {
-        const DismantleRewardPolicy& policy = before.dismantleRewards[policyIndex];
-        build_data::items::Definition definition{};
-        item_details::Definition detail{};
-        inventory_buckets::Descriptor bucket{};
-        if (policy.definitionHash == authored_inventory::kNoDefinitionHash || policy.quantity <= 0
-            || !build_data::find_item_definition_hash(policy.definitionHash, definition)
-            || definition.definitionHash != policy.definitionHash
-            || !build_data::find_configured_item_detail(definition.definitionIndex, detail)
-            || detail.definitionIndex != definition.definitionIndex
-            || detail.definitionHash != definition.definitionHash
-            || detail.bucketId != definition.bucketId
-            || detail.instancedDefinitionState != item_details::InstancedDefinitionState::stackable
-            || detail.maxStackSize <= 0
-            || !build_data::find_inventory_bucket_descriptor(detail.bucketId, bucket)
-            || bucket.arraySelector != inventory_buckets::ArraySelector::profile
-            || build_data::is_profile_action_source(definition.definitionIndex,
-                                                    definition.bucketId)) {
-            return false;
-        }
-
-        std::size_t profileIndex = after.profileItemCount;
-        for (std::size_t index = 0; index < after.profileItemCount; ++index) {
-            const authored_inventory::ProfileItem& item = after.profileItems[index];
-            if (item.definitionHash != policy.definitionHash) {
-                continue;
-            }
-            if (item.instanceSoid != 0 || item.quantity <= 0
-                || item.quantity > detail.maxStackSize) {
-                return false;
-            }
-            if (profileIndex == after.profileItemCount && item.quantity < detail.maxStackSize) {
-                profileIndex = index;
-            }
-        }
-
-        const bool appended = profileIndex == after.profileItemCount;
-        if ((appended && after.profileItemCount >= after.profileItems.size())
-            || greatestMutationSerial == (std::numeric_limits<std::int32_t>::max)()) {
-            continue;
-        }
-        const std::int32_t previousQuantity =
-            appended ? 0 : after.profileItems[profileIndex].quantity;
-        const std::int32_t available = detail.maxStackSize - previousQuantity;
-        const std::int32_t credited = (std::min)(policy.quantity, available);
-        if (credited <= 0) {
-            continue;
-        }
-
-        AccountState candidate = after;
-        const std::int32_t mutationSerial = greatestMutationSerial + 1;
-        const std::int32_t afterQuantity = previousQuantity + credited;
-        if (appended) {
-            candidate.profileItems[profileIndex] = {
-                0, policy.definitionHash, afterQuantity, mutationSerial};
-            ++candidate.profileItemCount;
-        } else {
-            candidate.profileItems[profileIndex].quantity = afterQuantity;
-            candidate.profileItems[profileIndex].mutationSerial = mutationSerial;
-        }
-        // A full native bucket drops this reward, but never blocks deletion of the source item.
-        if (!account::valid(candidate) || !valid_profile_inventory(candidate)) {
-            continue;
-        }
-        if (rewardCount >= rewards.size()) {
-            return false;
-        }
-        after = candidate;
-        greatestMutationSerial = mutationSerial;
-        rewards[rewardCount++] = {
-            policy.definitionHash, profileIndex, credited, afterQuantity, mutationSerial};
-    }
-    return account::valid(after) && valid_profile_inventory(after);
-}
-
-/**
- * Builds the one canonical dismantle transition for an exact account snapshot.
- *
- * Surviving authored entries keep their mutation generation unless installed row placement moves
- * them. Generation capacity is checked for every move before any survivor is changed.
- */
-[[nodiscard]] bool stage_item_dismantle(const AccountState& account,
-                                        std::size_t characterIndex,
-                                        std::uint64_t instanceSoid,
-                                        PendingItemDismantle& mutation) noexcept {
-    mutation = {};
-    if (instanceSoid == 0 || !account::valid(account) || characterIndex >= account.characterCount
-        || !account.characters[characterIndex].selected) {
-        return false;
-    }
-
-    const CharacterState& before = account.characters[characterIndex];
-    std::size_t inventoryIndex = before.inventory.count;
-    for (std::size_t index = 0; index < before.inventory.count; ++index) {
-        if (before.inventory.values[index].instanceSoid == instanceSoid) {
-            inventoryIndex = index;
-            break;
-        }
-    }
-    if (inventoryIndex >= before.inventory.count
-        || (before.inventory.values[inventoryIndex].flags & authored_inventory::kLockedItemFlag)
-               != 0) {
-        return false;
-    }
-
-    family4_loadout::ResolvedLoadout beforeLoadout{};
-    std::uint16_t dismantledRow = 0;
-    std::uint8_t dismantledSlot = 0;
-    if (!family4_loadout::resolve(account, characterIndex, beforeLoadout)
-        || before.nextInventorySerial
-               > static_cast<std::uint32_t>((std::numeric_limits<std::int32_t>::max)())
-        || !find_unequipped_row(beforeLoadout, instanceSoid, dismantledRow, dismantledSlot)) {
-        return false;
-    }
-
-    CharacterState after = before;
-    const authored_inventory::Item dismantledItem = after.inventory.values[inventoryIndex];
-    for (std::size_t index = inventoryIndex; index + 1U < after.inventory.count; ++index) {
-        after.inventory.values[index] = after.inventory.values[index + 1U];
-    }
-    --after.inventory.count;
-    after.inventory.values[after.inventory.count] = {};
-
-    AccountState candidate = account;
-    candidate.characters[characterIndex] = after;
-    family4_loadout::ResolvedLoadout placedAfter{};
-    if (!account::valid(candidate)
-        || !family4_loadout::resolve(candidate, characterIndex, placedAfter)
-        || loadout_contains(placedAfter, instanceSoid)
-        || beforeLoadout.itemCount != placedAfter.itemCount + 1U) {
-        return false;
-    }
-
-    std::size_t movedItemCount = 0;
-    for (std::size_t index = 0; index < after.inventory.count; ++index) {
-        const std::uint64_t survivorSoid = after.inventory.values[index].instanceSoid;
-        std::uint16_t beforeRow = 0;
-        std::uint16_t afterRow = 0;
-        std::uint8_t beforeSlot = 0;
-        std::uint8_t afterSlot = 0;
-        if (!find_unequipped_row(beforeLoadout, survivorSoid, beforeRow, beforeSlot)
-            || !find_unequipped_row(placedAfter, survivorSoid, afterRow, afterSlot)
-            || beforeSlot != afterSlot) {
-            return false;
-        }
-        movedItemCount += static_cast<std::size_t>(beforeRow != afterRow);
-    }
-
-    // The serial is signed on the wire, so it must stay inside the positive int32 range.
-    constexpr std::uint32_t kMaximumInventorySerial =
-        static_cast<std::uint32_t>((std::numeric_limits<std::int32_t>::max)());
-    if (after.nextInventorySerial > kMaximumInventorySerial
-        || movedItemCount > kMaximumInventorySerial - after.nextInventorySerial) {
-        return false;
-    }
-
-    for (std::size_t index = 0; index < after.inventory.count; ++index) {
-        const std::uint64_t survivorSoid = after.inventory.values[index].instanceSoid;
-        std::uint16_t beforeRow = 0;
-        std::uint16_t afterRow = 0;
-        std::uint8_t beforeSlot = 0;
-        std::uint8_t afterSlot = 0;
-        if (!find_unequipped_row(beforeLoadout, survivorSoid, beforeRow, beforeSlot)
-            || !find_unequipped_row(placedAfter, survivorSoid, afterRow, afterSlot)
-            || beforeSlot != afterSlot) {
-            return false;
-        }
-        if (beforeRow != afterRow) {
-            after.inventory.values[index].mutationSerial =
-                static_cast<std::int32_t>(after.nextInventorySerial++);
-        }
-    }
-
-    candidate.characters[characterIndex] = after;
-    family4_loadout::ResolvedLoadout checkedAfter{};
-    if (!account::valid(candidate)
-        || !family4_loadout::resolve(candidate, characterIndex, checkedAfter)
-        || checkedAfter.itemCount != placedAfter.itemCount
-        || loadout_contains(checkedAfter, instanceSoid)) {
-        return false;
-    }
-    for (std::size_t index = 0; index < after.inventory.count; ++index) {
-        const std::uint64_t survivorSoid = after.inventory.values[index].instanceSoid;
-        std::uint16_t placedRow = 0;
-        std::uint16_t checkedRow = 0;
-        std::uint8_t placedSlot = 0;
-        std::uint8_t checkedSlot = 0;
-        if (!find_unequipped_row(placedAfter, survivorSoid, placedRow, placedSlot)
-            || !find_unequipped_row(checkedAfter, survivorSoid, checkedRow, checkedSlot)
-            || placedRow != checkedRow || placedSlot != checkedSlot) {
-            return false;
-        }
-    }
-
-    build_data::items::Definition dismantledDefinition{};
-    item_details::Definition dismantledDetail{};
-    if (!build_data::find_item_definition_hash(dismantledItem.definitionHash, dismantledDefinition)
-        || dismantledDefinition.definitionHash != dismantledItem.definitionHash
-        || !build_data::find_configured_item_detail(dismantledDefinition.definitionIndex,
-                                                    dismantledDetail)
-        || dismantledDetail.definitionIndex != dismantledDefinition.definitionIndex
-        || dismantledDetail.definitionHash != dismantledDefinition.definitionHash
-        || dismantledDetail.bucketId != dismantledDefinition.bucketId
-        || dismantledDetail.instancedDefinitionState
-               != item_details::InstancedDefinitionState::instanced
-        || !dismantledDetail.equipmentSlot.has_value()
-        || static_cast<std::uint8_t>(*dismantledDetail.equipmentSlot) != dismantledSlot) {
-        return false;
-    }
-
-    AccountState rewarded{};
-    std::array<DismantleReward, kDismantleRewardCapacity> rewards{};
-    std::size_t rewardCount = 0;
-    if (!apply_dismantle_rewards(candidate, dismantledSlot, rewarded, rewards, rewardCount)) {
-        return false;
-    }
-    candidate = rewarded;
-
-    mutation.beforeCharacter = before;
-    mutation.afterCharacter = after;
-    mutation.beforeProfileItems = account.profileItems;
-    mutation.afterProfileItems = candidate.profileItems;
-    mutation.rewards = rewards;
-    mutation.dismantledItem = dismantledItem;
-    mutation.accountSoid = account.primarySoid;
-    mutation.characterSoid = before.soid;
-    mutation.dismantledInstanceSoid = instanceSoid;
-    mutation.characterIndex = characterIndex;
-    mutation.expectedInventoryCount = before.inventory.count;
-    mutation.expectedProfileItemCount = account.profileItemCount;
-    mutation.afterProfileItemCount = candidate.profileItemCount;
-    mutation.inventoryIndex = inventoryIndex;
-    mutation.movedInventoryItemCount = movedItemCount;
-    mutation.rewardCount = rewardCount;
-    mutation.inventoryRow = dismantledRow;
-    mutation.equipmentSlot = dismantledSlot;
-    mutation.profileChanged = rewardCount != 0;
-    mutation.prepared = true;
-    return true;
-}
-
-/** @return True when both descriptions name the same credited profile mutation. */
-[[nodiscard]] bool same_dismantle_reward(const DismantleReward& left,
-                                         const DismantleReward& right) noexcept {
-    return left.definitionHash == right.definitionHash && left.profileIndex == right.profileIndex
-           && left.quantity == right.quantity && left.afterQuantity == right.afterQuantity
-           && left.mutationSerial == right.mutationSerial;
-}
-
-/** @return True when two independently staged dismantles carry the exact same after-images. */
-[[nodiscard]] bool same_dismantle_transition(const PendingItemDismantle& left,
-                                             const PendingItemDismantle& right) noexcept {
-    if (left.prepared != right.prepared || left.accountSoid != right.accountSoid
-        || left.characterSoid != right.characterSoid
-        || left.dismantledInstanceSoid != right.dismantledInstanceSoid
-        || left.characterIndex != right.characterIndex
-        || left.expectedInventoryCount != right.expectedInventoryCount
-        || left.expectedProfileItemCount != right.expectedProfileItemCount
-        || left.afterProfileItemCount != right.afterProfileItemCount
-        || left.inventoryIndex != right.inventoryIndex
-        || left.movedInventoryItemCount != right.movedInventoryItemCount
-        || left.rewardCount != right.rewardCount || left.inventoryRow != right.inventoryRow
-        || left.equipmentSlot != right.equipmentSlot || left.profileChanged != right.profileChanged
-        || !same_stationary_item(left.dismantledItem, right.dismantledItem)
-        || !same_character(left.beforeCharacter, right.beforeCharacter)
-        || !same_character(left.afterCharacter, right.afterCharacter)
-        || !same_profile_views(left.beforeProfileItems,
-                               left.expectedProfileItemCount,
-                               right.beforeProfileItems,
-                               right.expectedProfileItemCount)
-        || !same_profile_views(left.afterProfileItems,
-                               left.afterProfileItemCount,
-                               right.afterProfileItems,
-                               right.afterProfileItemCount)) {
-        return false;
-    }
-    for (std::size_t index = 0; index < left.rewards.size(); ++index) {
-        if (!same_dismantle_reward(left.rewards[index], right.rewards[index])) {
-            return false;
-        }
-    }
-    return true;
-}
-
-/** Applies a fully checked dismantle after-image over an exact current account view. */
-[[nodiscard]] bool materialize_item_dismantle(const AccountState& current,
-                                              const PendingItemDismantle& mutation,
-                                              AccountState& after) noexcept {
-    after = {};
-    if (!mutation.prepared || mutation.accountSoid == 0 || mutation.characterSoid == 0
-        || mutation.dismantledInstanceSoid == 0
-        || mutation.dismantledItem.instanceSoid != mutation.dismantledInstanceSoid
-        || mutation.dismantledItem.definitionHash == authored_inventory::kNoDefinitionHash
-        || mutation.characterIndex >= current.characterCount || mutation.expectedInventoryCount == 0
-        || mutation.expectedInventoryCount > authored_inventory::kCharacterItemCapacity
-        || mutation.expectedProfileItemCount > authored_inventory::kProfileItemCapacity
-        || mutation.afterProfileItemCount > authored_inventory::kProfileItemCapacity
-        || mutation.inventoryIndex >= mutation.expectedInventoryCount
-        || mutation.rewardCount > mutation.rewards.size()
-        || mutation.profileChanged != (mutation.rewardCount != 0)
-        || mutation.beforeCharacter.soid != mutation.characterSoid
-        || mutation.afterCharacter.soid != mutation.characterSoid
-        || mutation.beforeCharacter.inventory.count != mutation.expectedInventoryCount
-        || mutation.afterCharacter.inventory.count + 1U != mutation.expectedInventoryCount
-        || !same_stationary_item(mutation.beforeCharacter.inventory.values[mutation.inventoryIndex],
-                                 mutation.dismantledItem)
-        || current.primarySoid != mutation.accountSoid
-        || !same_profile_inventory(
-            current, mutation.beforeProfileItems, mutation.expectedProfileItemCount)) {
-        return false;
-    }
-    const CharacterState& character = current.characters[mutation.characterIndex];
-    if (!character.selected || character.soid != mutation.characterSoid
-        || !same_character(character, mutation.beforeCharacter)) {
-        return false;
-    }
-    for (std::size_t index = 0; index < mutation.rewards.size(); ++index) {
-        const DismantleReward& reward = mutation.rewards[index];
-        if (index < mutation.rewardCount) {
-            if (reward.definitionHash == authored_inventory::kNoDefinitionHash
-                || reward.profileIndex >= mutation.afterProfileItemCount || reward.quantity <= 0
-                || reward.afterQuantity < reward.quantity || reward.mutationSerial <= 0) {
-                return false;
-            }
-            const authored_inventory::ProfileItem& row =
-                mutation.afterProfileItems[reward.profileIndex];
-            if (row.instanceSoid != 0 || row.definitionHash != reward.definitionHash
-                || row.quantity != reward.afterQuantity
-                || row.mutationSerial != reward.mutationSerial) {
-                return false;
-            }
-        } else if (reward.definitionHash != 0 || reward.profileIndex != 0 || reward.quantity != 0
-                   || reward.afterQuantity != 0 || reward.mutationSerial != 0) {
-            return false;
-        }
-    }
-    if (!mutation.profileChanged
-        && !same_profile_views(mutation.beforeProfileItems,
-                               mutation.expectedProfileItemCount,
-                               mutation.afterProfileItems,
-                               mutation.afterProfileItemCount)) {
-        return false;
-    }
-
-    PendingItemDismantle canonical{};
-    if (!stage_item_dismantle(
-            current, mutation.characterIndex, mutation.dismantledInstanceSoid, canonical)
-        || !same_dismantle_transition(canonical, mutation)) {
-        return false;
-    }
-
-    after = current;
-    after.characters[mutation.characterIndex] = mutation.afterCharacter;
-    after.profileItems = mutation.afterProfileItems;
-    after.profileItemCount = mutation.afterProfileItemCount;
-    return account::valid(after) && valid_profile_inventory(after)
-           && !identity_uses_soid(after, mutation.dismantledInstanceSoid);
-}
-
 } // namespace runtime::detail
 
 using namespace runtime::detail;

Sunrise/src/state/runtime/state_account_socket_runtime.cpp

@@ -0,0 +1,363 @@
+/** Socket-plug and item-state staging, which both mutate one character-owned item. */
+
+#include <Windows.h>
+
+#include <algorithm>
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <cstdio>
+#include <limits>
+#include <string_view>
+#include <utility>
+
+#include "../../core/logging/log.h"
+#include "../../middleware/datagen/family4/loadout/loadout_resolver.h"
+#include "../build_data/runtime.h"
+#include "runtime.h"
+#include "state.h"
+#include "state_account_transaction_helpers.h"
+#include "storage/internal.h"
+
+namespace sunrise::state {
+namespace runtime::detail {
+
+namespace authored_inventory = account::inventory;
+namespace item_details = build_data::items::details;
+namespace inventory_buckets = build_data::inventory::buckets;
+namespace family4_loadout = middleware::datagen::family4::loadout;
+
+/** Writes one bounded opcode-903 socket-selection transaction checkpoint. */
+void report_socket_plug(std::string_view stage,
+                        std::string_view result,
+                        std::string_view reason,
+                        std::uint64_t characterSoid,
+                        std::uint64_t targetInstanceSoid,
+                        std::uint16_t targetDefinitionIndex,
+                        std::uint8_t socketLane,
+                        std::uint16_t plugDefinitionIndex,
+                        std::uint8_t targetBucketId,
+                        std::uint8_t plugBucketId,
+                        bool targetEquipped,
+                        std::size_t itemIndex) noexcept {
+    std::array<char, core::log::kLineCapacity> line{};
+    const int count = std::snprintf(
+        line.data(),
+        line.size(),
+        "ev=socket_plug stage=%.*s result=%.*s reason=%.*s character=0x%llX "
+        "instance=0x%llX target_definition=%u target_bucket=%u lane=%u plug_definition=%u "
+        "plug_bucket=%u equipped=%u item_index=%zu",
+        static_cast<int>(stage.size()),
+        stage.data(),
+        static_cast<int>(result.size()),
+        result.data(),
+        static_cast<int>(reason.size()),
+        reason.data(),
+        static_cast<unsigned long long>(characterSoid),
+        static_cast<unsigned long long>(targetInstanceSoid),
+        static_cast<unsigned>(targetDefinitionIndex),
+        static_cast<unsigned>(targetBucketId),
+        static_cast<unsigned>(socketLane),
+        static_cast<unsigned>(plugDefinitionIndex),
+        static_cast<unsigned>(plugBucketId),
+        static_cast<unsigned>(targetEquipped),
+        itemIndex);
+    if (count > 0) {
+        core::log::write(core::log::Channel::state,
+                         result == "ok" ? core::log::Level::debug : core::log::Level::warn,
+                         {line.data(), static_cast<std::size_t>(count)});
+    }
+}
+
+/** Materializes native initial plugs as a complete authored socket block. */
+[[nodiscard]] bool materialize_native_sockets(const item_details::Definition& detail,
+                                              authored_inventory::Sockets& sockets) noexcept {
+    sockets = {};
+    if (detail.ordinarySocketState != item_details::OrdinarySocketState::present
+        || detail.ordinarySocketCount > sockets.plugs.size()) {
+        return false;
+    }
+    sockets.policy = authored_inventory::SocketPolicy::authored;
+    sockets.plugCount = detail.ordinarySocketCount;
+    for (std::size_t lane = 0; lane < sockets.plugCount; ++lane) {
+        const std::uint16_t plugIndex = detail.initialPlugIndices[lane];
+        if (plugIndex == item_details::kUnavailableItemIndex) {
+            continue;
+        }
+        build_data::items::Definition plug{};
+        if (!build_data::find_item_definition_index(plugIndex, plug)
+            || plug.definitionIndex != plugIndex
+            || plug.definitionHash == authored_inventory::kNoDefinitionHash) {
+            return false;
+        }
+        sockets.plugs[lane] = plug.definitionHash;
+    }
+    return authored_inventory::valid(sockets);
+}
+
+/** Stages the canonical socket-only after-image over one already validated account snapshot. */
+[[nodiscard]] bool stage_socket_plug(const AccountState& snapshot,
+                                     std::size_t characterIndex,
+                                     std::uint64_t targetInstanceSoid,
+                                     std::uint8_t socketLane,
+                                     std::uint16_t plugDefinitionIndex,
+                                     PendingSocketPlug& mutation) noexcept {
+    mutation = {};
+    CharacterItemLocation location{};
+    build_data::items::Definition targetDefinition{};
+    build_data::items::Definition plugDefinition{};
+    const auto fail = [&](std::string_view reason) noexcept {
+        const std::uint64_t characterSoid =
+            characterIndex < snapshot.characterCount ? snapshot.characters[characterIndex].soid : 0;
+        report_socket_plug("stage_internal",
+                           "fail",
+                           reason,
+                           characterSoid,
+                           targetInstanceSoid,
+                           targetDefinition.definitionIndex,
+                           socketLane,
+                           plugDefinitionIndex,
+                           targetDefinition.bucketId,
+                           plugDefinition.bucketId,
+                           location.equipped,
+                           location.index);
+        mutation = {};
+        return false;
+    };
+    if (!account::valid(snapshot) || characterIndex >= snapshot.characterCount
+        || targetInstanceSoid == 0 || socketLane >= authored_inventory::kPlugCapacity) {
+        return fail("request_or_account");
+    }
+    const CharacterState& before = snapshot.characters[characterIndex];
+    if (!before.selected || before.soid == 0) {
+        return fail("selected_character");
+    }
+
+    family4_loadout::ResolvedLoadout beforeLoadout{};
+    if (!find_character_item_location(before, targetInstanceSoid, location)
+        || !family4_loadout::resolve(snapshot, characterIndex, beforeLoadout)) {
+        return fail("target_or_before_loadout");
+    }
+    const authored_inventory::Item* target = character_item_at(before, location);
+    item_details::Definition detail{};
+    if (target == nullptr
+        || !build_data::find_item_definition_hash(target->definitionHash, targetDefinition)
+        || targetDefinition.definitionHash != target->definitionHash
+        || !build_data::find_configured_item_detail(targetDefinition.definitionIndex, detail)
+        || detail.definitionIndex != targetDefinition.definitionIndex
+        || detail.definitionHash != targetDefinition.definitionHash
+        || detail.bucketId != targetDefinition.bucketId
+        || detail.ordinarySocketState != item_details::OrdinarySocketState::present
+        || socketLane >= detail.ordinarySocketCount
+        || detail.ordinarySocketCount > authored_inventory::kPlugCapacity
+        || !build_data::find_item_definition_index(plugDefinitionIndex, plugDefinition)
+        || plugDefinition.definitionIndex != plugDefinitionIndex
+        || plugDefinition.definitionHash == authored_inventory::kNoDefinitionHash
+        || !build_data::is_socket_plug_allowed(
+            targetDefinition.definitionIndex, socketLane, plugDefinitionIndex)) {
+        return fail("definition_or_compatibility");
+    }
+
+    // Ownership is only meaningful where the plug is a finite supply the account draws down. A
+    // shader is one: it is pulled from Collections into a profile stack and spent by applying it.
+    // An ornament is a permanent unlock the account holds once earned, not a stack it draws
+    // down, which is why the Client offers every valid one for a socket. Requiring a stack for
+    // one would refuse a plug the account already has.
+    const bool consumesStack =
+        build_data::is_profile_action_source(plugDefinitionIndex, plugDefinition.bucketId)
+        && build_data::is_consumed_on_apply(plugDefinitionIndex, plugDefinition.bucketId)
+        && !(socketLane < detail.initialPlugIndices.size()
+             && detail.initialPlugIndices[socketLane] == plugDefinitionIndex);
+    if (consumesStack && !holds_plug_source(snapshot, plugDefinition.definitionHash)) {
+        return fail("plug_ownership");
+    }
+
+    AccountState chargedAccount = snapshot;
+    build_data::material_requirements::Definition materialSet{};
+    bool profileChanged = false;
+    const std::uint16_t materialSetIndex = plugDefinition.insertionMaterialRequirementSetIndex;
+    if (materialSetIndex != build_data::items::kUnavailableMaterialRequirementSetIndex
+        && (!build_data::find_material_requirement_set(materialSetIndex, materialSet)
+            || materialSet.requirementSetIndex != materialSetIndex
+            || !apply_action_materials(snapshot, materialSet, chargedAccount, profileChanged))) {
+        return fail("materials");
+    }
+
+    // Applying spends the stack the plug came from. The insertion cost above is a separate
+    // authored charge that leaves the plug itself untouched, so the unit is taken here.
+    //
+    // The authored-cost path cannot do this. It refuses any row carrying an instance key, because
+    // it exists for the non-instanced currency and material stacks, and an action source always
+    // carries one. Spending one is therefore its own transition: the row keeps its identity while
+    // any unit remains, and releases it with the row once the last unit goes.
+    if (consumesStack && !spend_plug_source(chargedAccount, plugDefinition.definitionHash)) {
+        return fail("plug_stack");
+    }
+    profileChanged = profileChanged || consumesStack;
+
+    authored_inventory::Sockets authoredSockets{};
+    if (target->sockets.policy == authored_inventory::SocketPolicy::nativeDefaults) {
+        if (!materialize_native_sockets(detail, authoredSockets)) {
+            return fail("native_sockets");
+        }
+    } else {
+        authoredSockets = target->sockets;
+        if (authoredSockets.policy != authored_inventory::SocketPolicy::authored
+            || authoredSockets.plugCount != detail.ordinarySocketCount
+            || !authored_inventory::valid(authoredSockets)) {
+            return fail("authored_sockets");
+        }
+    }
+    if (authoredSockets.plugs[socketLane].has_value()
+        && *authoredSockets.plugs[socketLane] == plugDefinition.definitionHash) {
+        return fail("already_applied");
+    }
+    authoredSockets.plugs[socketLane] = plugDefinition.definitionHash;
+
+    CharacterState after = before;
+    authored_inventory::Item* changed = character_item_at(after, location);
+    if (changed == nullptr || changed->instanceSoid != target->instanceSoid
+        || changed->definitionHash != target->definitionHash || changed->level != target->level
+        || changed->quantity != target->quantity
+        || changed->mutationSerial != target->mutationSerial) {
+        return fail("target_copy");
+    }
+    changed->sockets = authoredSockets;
+
+    AccountState candidate = chargedAccount;
+    candidate.characters[characterIndex] = after;
+    family4_loadout::ResolvedLoadout afterLoadout{};
+    ResolvedPosition beforePosition{};
+    ResolvedPosition afterPosition{};
+    const family4_loadout::ResolvedItem* resolvedTarget = nullptr;
+    for (std::size_t index = 0; index < beforeLoadout.itemCount; ++index) {
+        const auto& resolved = beforeLoadout.items[index];
+        if (resolved.instance.instanceSoid == targetInstanceSoid
+            && resolved.instance.baseDefinitionIndex != targetDefinition.definitionIndex) {
+            return fail("before_definition");
+        }
+    }
+    if (!account::valid(candidate)
+        || !family4_loadout::resolve(candidate, characterIndex, afterLoadout)
+        || !find_resolved_position(beforeLoadout, targetInstanceSoid, beforePosition)
+        || !find_resolved_position(afterLoadout, targetInstanceSoid, afterPosition)
+        || !same_position(beforePosition, afterPosition)) {
+        return fail("candidate_or_position");
+    }
+    for (std::size_t index = 0; index < afterLoadout.itemCount; ++index) {
+        const auto& resolved = afterLoadout.items[index];
+        if (resolved.instance.instanceSoid != targetInstanceSoid) {
+            continue;
+        }
+        if (resolvedTarget != nullptr) {
+            return fail("duplicate_target");
+        }
+        resolvedTarget = &resolved;
+    }
+    if (resolvedTarget == nullptr
+        || resolvedTarget->instance.baseDefinitionIndex != targetDefinition.definitionIndex
+        || resolvedTarget->instance.ordinarySockets.state
+               != middleware::datagen::family4::instance::OrdinarySocketBlockState::present
+        || !resolvedTarget->instance.ordinarySockets.plugs[socketLane].has_value()
+        || *resolvedTarget->instance.ordinarySockets.plugs[socketLane] != plugDefinitionIndex) {
+        return fail("after_socket");
+    }
+
+    mutation.beforeCharacter = before;
+    mutation.afterCharacter = after;
+    mutation.beforeProfileItems = snapshot.profileItems;
+    mutation.afterProfileItems = chargedAccount.profileItems;
+    mutation.accountSoid = snapshot.primarySoid;
+    mutation.characterSoid = before.soid;
+    mutation.targetInstanceSoid = targetInstanceSoid;
+    mutation.targetDefinitionHash = targetDefinition.definitionHash;
+    mutation.plugDefinitionHash = plugDefinition.definitionHash;
+    mutation.materialRequirementSetHash = materialSet.requirementSetHash;
+    mutation.characterIndex = characterIndex;
+    mutation.expectedProfileItemCount = snapshot.profileItemCount;
+    mutation.afterProfileItemCount = chargedAccount.profileItemCount;
+    mutation.itemIndex = location.index;
+    mutation.targetDefinitionIndex = targetDefinition.definitionIndex;
+    mutation.plugDefinitionIndex = plugDefinitionIndex;
+    mutation.materialRequirementSetIndex = materialSetIndex;
+    mutation.socketLane = socketLane;
+    mutation.targetBucketId = targetDefinition.bucketId;
+    mutation.plugBucketId = plugDefinition.bucketId;
+    mutation.materialRequirementCount = materialSet.requirementCount;
+    mutation.profileChanged = profileChanged;
+    mutation.targetEquipped = location.equipped;
+    mutation.prepared = true;
+    return true;
+}
+
+/** Stages one complete accumulated item-state value without moving or recreating the item. */
+[[nodiscard]] bool stage_item_state(const AccountState& snapshot,
+                                    std::size_t characterIndex,
+                                    std::uint64_t targetInstanceSoid,
+                                    std::uint16_t targetDefinitionIndex,
+                                    std::uint32_t flags,
+                                    PendingItemState& mutation) noexcept {
+    mutation = {};
+    // Bits 0 and 1 are the two states the client sends. Any other bit is a request we cannot
+    // honour.
+    constexpr std::uint32_t kSupportedItemStateMask = 0x3U;
+    if (!account::valid(snapshot) || characterIndex >= snapshot.characterCount
+        || targetInstanceSoid == 0 || (flags & ~kSupportedItemStateMask) != 0) {
+        return false;
+    }
+    const CharacterState& before = snapshot.characters[characterIndex];
+    if (!before.selected || before.soid == 0) {
+        return false;
+    }
+
+    CharacterItemLocation location{};
+    family4_loadout::ResolvedLoadout beforeLoadout{};
+    if (!find_character_item_location(before, targetInstanceSoid, location)
+        || !family4_loadout::resolve(snapshot, characterIndex, beforeLoadout)) {
+        return false;
+    }
+    const authored_inventory::Item* target = character_item_at(before, location);
+    build_data::items::Definition definition{};
+    ResolvedPosition beforePosition{};
+    if (target == nullptr || target->flags == flags
+        || !build_data::find_item_definition_hash(target->definitionHash, definition)
+        || definition.definitionHash != target->definitionHash
+        || definition.definitionIndex != targetDefinitionIndex
+        || !find_resolved_position(beforeLoadout, targetInstanceSoid, beforePosition)) {
+        return false;
+    }
+
+    CharacterState after = before;
+    authored_inventory::Item* changed = character_item_at(after, location);
+    if (changed == nullptr || !same_stationary_item(*changed, *target)) {
+        return false;
+    }
+    changed->flags = flags;
+
+    AccountState candidate = snapshot;
+    candidate.characters[characterIndex] = after;
+    family4_loadout::ResolvedLoadout afterLoadout{};
+    ResolvedPosition afterPosition{};
+    if (!account::valid(candidate)
+        || !family4_loadout::resolve(candidate, characterIndex, afterLoadout)
+        || !find_resolved_position(afterLoadout, targetInstanceSoid, afterPosition)
+        || !same_position(beforePosition, afterPosition)) {
+        return false;
+    }
+
+    mutation.beforeCharacter = before;
+    mutation.afterCharacter = after;
+    mutation.characterSoid = before.soid;
+    mutation.targetInstanceSoid = targetInstanceSoid;
+    mutation.characterIndex = characterIndex;
+    mutation.itemIndex = location.index;
+    mutation.targetDefinitionIndex = targetDefinitionIndex;
+    mutation.beforeFlags = target->flags;
+    mutation.afterFlags = flags;
+    mutation.targetEquipped = location.equipped;
+    mutation.prepared = true;
+    return true;
+}
+
+} // namespace runtime::detail
+} // namespace sunrise::state

Sunrise/src/state/runtime/state_account_transaction_helpers.h

@@ -18,6 +18,12 @@ struct ResolvedPosition {
     std::int32_t mutationSerial{};
 };
 
+/** Stable location of one character-owned item inside authored State. */
+struct CharacterItemLocation {
+    std::size_t index{};
+    bool equipped{};
+};
+
 void report_equipment(std::string_view stage,
                       std::string_view result,
                       EquipmentMutationKind kind,
@@ -159,5 +165,36 @@ find_acquired_row(const middleware::datagen::family4::loadout::ResolvedLoadout&
                                               const PendingItemDismantle& mutation,
                                               AccountState& after) noexcept;
 [[nodiscard]] bool identity_uses_soid(const AccountState& account, std::uint64_t soid) noexcept;
+[[nodiscard]] bool holds_plug_source(const AccountState& account,
+                                     std::uint32_t definitionHash) noexcept;
+[[nodiscard]] bool spend_plug_source(AccountState& account, std::uint32_t definitionHash) noexcept;
+[[nodiscard]] bool
+apply_action_materials(const AccountState& before,
+                       const build_data::material_requirements::Definition& definition,
+                       AccountState& after,
+                       bool& changed) noexcept;
+[[nodiscard]] bool inventory_bucket_id(const account::inventory::Item& item,
+                                       std::uint8_t& bucketId) noexcept;
+[[nodiscard]] bool same_position(const ResolvedPosition& left,
+                                 const ResolvedPosition& right) noexcept;
+[[nodiscard]] bool same_stationary_item(const account::inventory::Item& left,
+                                        const account::inventory::Item& right) noexcept;
+[[nodiscard]] bool find_character_item_location(const CharacterState& character,
+                                                std::uint64_t instanceSoid,
+                                                CharacterItemLocation& location) noexcept;
+[[nodiscard]] const account::inventory::Item*
+character_item_at(const CharacterState& character, const CharacterItemLocation& location) noexcept;
+[[nodiscard]] account::inventory::Item*
+character_item_at(CharacterState& character, const CharacterItemLocation& location) noexcept;
+[[nodiscard]] std::uint32_t character_item_definition_hash(const CharacterState& character,
+                                                           std::uint64_t instanceSoid) noexcept;
+[[nodiscard]] bool
+find_unequipped_row(const middleware::datagen::family4::loadout::ResolvedLoadout& loadout,
+                    std::uint64_t instanceSoid,
+                    std::uint16_t& inventoryRow,
+                    std::uint8_t& equipmentSlot) noexcept;
+[[nodiscard]] bool
+loadout_contains(const middleware::datagen::family4::loadout::ResolvedLoadout& loadout,
+                 std::uint64_t instanceSoid) noexcept;
 
 } // namespace sunrise::state::runtime::detail