Narrow retained UI overlay lifetime debt

src/ui_core/node_lifetime.h

@@ -82,6 +82,12 @@ private:
 
 class NodeLifetimeTree {
 public:
+    // Thread-affinity and mutation contract:
+    // - Node and callback handles are generation-validated on each lookup.
+    // - Destroyed, disconnected, or stale handles are rejected with explicit status.
+    // - Mutations may occur during callback dispatch. Callbacks execute from a
+    //   captured snapshot, so create/remove connections and destroy subtrees are
+    //   safely observed by the current dispatch loop.
     using Callback = std::function<void(NodeHandle)>;
 
     [[nodiscard]] pp::foundation::Result<NodeHandle> create_root();