feat(#2500): hive-jobq scheduler settle loop (owned resources + subtree-hold)

hive-jobq/src/lib.rs

@@ -26,11 +26,12 @@
 //! node kind. Resources are held by the acquiring node and released on
 //! completion via guard objects, recursive within a group.
 //!
-//! The scheduler loop is a follow-up; the resource machinery lives in
-//! [`resources`] and the RAII lock guards over it in [`guard`].
+//! The [`scheduler`] settle loop drives execution; the resource machinery
+//! lives in [`resources`] and the RAII lock guards over it in [`guard`].
 
 pub mod guard;
 pub mod resources;
+pub mod scheduler;
 
 /// Opaque, stable, monotonic node identifier.
 ///
@@ -291,6 +292,24 @@ impl<N> Graph<N> {
         self.nodes.iter().filter(move |n| n.parent == Some(id))
     }
 
+    /// Every node in the graph, in insertion order. The scheduler iterates
+    /// this to find runnable pending nodes.
+    pub fn nodes(&self) -> impl Iterator<Item = &Node<N>> {
+        self.nodes.iter()
+    }
+
+    /// Set a node's lifecycle state, returning `false` for an unknown id. The
+    /// scheduler drives every state transition — nothing else mutates state,
+    /// which is what keeps the resource guards + terminality in sync.
+    pub fn set_state(&mut self, id: NodeId, state: State) -> bool {
+        if let Some(node) = self.nodes.iter_mut().find(|n| n.id == id) {
+            node.state = state;
+            true
+        } else {
+            false
+        }
+    }
+
     /// A group is terminal once the group node itself is terminal *and* every
     /// node inside it (recursively) is terminal. The node's own state matters:
     /// a group node still `Pending`/`Running` is not terminal even with no