Closes #22

core/tree_node.h

@@ -14,9 +14,11 @@
 
 #include <cstddef>
 #include <memory>
+#include <optional>
 #include <string>
 #include <vector>
 
+#include "definition_key.h"
 #include "frame_info.h"
 #include "signal_info.h"
 
@@ -56,14 +58,19 @@ public:
     TreeNode(const TreeNode &) = delete;
     TreeNode &operator=(const TreeNode &) = delete;
 
+    // Node addresses are stable. Transfer unique_ptr ownership instead of nodes.
     TreeNode(TreeNode &&) = delete;
     TreeNode &operator=(TreeNode &&) = delete;
 
     /**
      * @brief Add child node.
      * @param child Child node to add.
+     * A null child is ignored. Existing children keep their addresses and rows.
+     * Ownership must be exclusive; attached nodes cannot be reparented.
+     * @throws std::invalid_argument for self/ancestor insertion or an attached child.
+     * Rejected ownership remains with the caller.
      */
-    void AddChild(std::unique_ptr<TreeNode> child);
+    void AddChild(std::unique_ptr<TreeNode> &&child);
 
     /** Non-owning parent; nullptr for a detached node or the root. */
     const TreeNode *GetParent() const;
@@ -71,6 +78,12 @@ public:
     /** Zero-based sibling position; zero for a detached node or the root. */
     std::size_t GetRow() const;
 
+    /** Frame identity for frame nodes and signals attached to a frame; otherwise empty. */
+    std::optional<FrameKey> GetFrameKey() const;
+
+    /** Signal identity (owning frame key and name); empty for other/detached nodes. */
+    std::optional<SignalKey> GetSignalKey() const;
+
     /**
      * @brief Get child count.
      * @return Number of children.