docs(investment): document catalyst extraction seams

Sunrise/src/client/content/items/packages/package_catalyst_condition_reader.cpp

@@ -19,6 +19,12 @@ constexpr std::size_t kCompletionExpressionTokenCount = 3;
 
 } // namespace
 
+/**
+ * Finds the unique three-token `value >= literal` completion rule in one effect item.
+ * @param definition Complete installed definition of the catalyst effect item.
+ * @param itemDefinitionIndex Native index of the catalyst effect item.
+ * @param output Receives the unique condition or its absent or ambiguous state.
+ */
 void read_catalyst_completion_condition(
     std::span<const std::byte> definition,
     std::uint16_t itemDefinitionIndex,

Sunrise/src/client/content/items/packages/package_socket_plug_build.cpp

@@ -56,6 +56,15 @@ struct VisitorContext {
 
 } // namespace
 
+/**
+ * Reads the dense socket-type table and extracts each type's acquired-state gate.
+ * @param source Installed package source.
+ * @param scratch Shared package reader scratch.
+ * @param root Investment root bytes.
+ * @param blob Scratch storage for the socket-type table.
+ * @param output Receives one row per native socket type.
+ * @return True when the fixed table shape and every row extent are valid.
+ */
 bool read_catalyst_acquisition_gates(
     const reader::Source& source,
     reader::Scratch& scratch,

Sunrise/src/client/content/items/packages/package_socket_plug_build.h

@@ -39,6 +39,9 @@ namespace catalysts = state::build_data::items::catalysts;
  * Finds the unique three-token `value >= literal` completion rule in one effect item.
  * Duplicate expressions with the same values remain one condition. Distinct matches are marked
  * ambiguous so a released catalyst fails before publication.
+ * @param definition Complete installed definition of the catalyst effect item.
+ * @param itemDefinitionIndex Native index of the catalyst effect item.
+ * @param output Receives the unique condition or its absent or ambiguous state.
  */
 void read_catalyst_completion_condition(
     std::span<const std::byte> definition,

Sunrise/src/middleware/datagen/character_record/appearance/character_appearance_render.cpp

@@ -152,7 +152,12 @@ bool resolve_equipped(const family4::loadout::SlottedInstance& slotted,
     return true;
 }
 
-/** Resolves one socketed plug to the item row that supplies its perks and stats. */
+/**
+ * Resolves one socketed plug to the item row that supplies its perks and stats.
+ * @param equipped Equipped base item and its visible socket plugs.
+ * @param lane Zero-based ordinary socket lane.
+ * @return Effective plug definition, or the unavailable sentinel for an invalid lane.
+ */
 std::uint16_t resolve_effective_plug(const Equipped& equipped, std::size_t lane) noexcept {
     if (lane >= equipped.laneCount || lane >= equipped.plugs.size()) {
         return details::kUnavailableItemIndex;