wip(#3001): rename insert -> insert_job per mara's 50056

hive-c0re/src/job_queue/mod.rs

@@ -188,27 +188,24 @@ impl JobQueue {
         self.sched.lock().expect("job_queue mutex poisoned")
     }
 
-    /// Submit a DAG: insert a [`NodeKind::Dag`] **container node** carrying the
-    /// group's metadata, then insert the template's nodes as its subtree (their
-    /// roots re-parented to the container). Returns the container's id as the
-    /// DAG id — its rolled-up state is the DAG state.
+    /// Insert a job's nodes into the shared graph, then wake the run loop.
     ///
-    /// The container is an ordinary node: it declares no resources, so the
-    /// scheduler claims it on the next pass, runs its (empty) logic and parks
-    /// it in `Finishing`, at which point its children become runnable. Nothing
-    /// here completes it by hand — a node with no work of its own still goes
-    /// the way every other node goes.
+    /// Deliberately named for the [`hive_jobq`] primitive it wraps, because
+    /// that is nearly all it is. **The wrapper earns its place on the wake**:
+    /// the crate is sync and runtime-free — it holds no `Notify` at all — so
+    /// the channel the run loop parks on belongs to the host, and something has
+    /// to ping it. Left to call sites, an insert whose ping was forgotten would
+    /// leave a correct DAG sitting unscheduled until an unrelated event
+    /// happened along; nothing would fail, and no test in isolation would see
+    /// it.
     ///
-    /// `source` and `reason` are the container node's own payload — they are
-    /// arguments here rather than fields of a spec struct because that is all
-    /// they ever were. `declare` is the recipe, taken by generic and run
-    /// against a builder `hive_jobq` owns: it goes from the template straight
-    /// into this call, so there is nothing to allocate for.
+    /// Returns exactly what the primitive returns: the ids of the nodes the
+    /// template named, in the order it named them.
     ///
     /// # Errors
     /// Propagates a graph-insert error (dependencies that aren't
     /// dependency-topological).
-    pub fn insert(
+    pub fn insert_job(
         &self,
         declare: impl FnOnce(&JobBuilder) -> Vec<hive_jobq::NodeGuid>,
     ) -> anyhow::Result<Vec<NodeId>> {

hive-c0re/src/job_queue/power.rs

@@ -216,7 +216,7 @@ pub async fn restart_many(
     for agent in agents {
         targets.push((agent.clone(), lifecycle::is_running(agent).await));
     }
-    let ids = coord.job_queue.insert(|b| {
+    let ids = coord.job_queue.insert_job(|b| {
         restart_nodes(b, &targets, graceful);
         Vec::new()
     })?;
@@ -245,7 +245,7 @@ pub async fn start_many(coord: &Arc<Coordinator>, agents: &[String]) -> anyhow::
         }
         targets.push((agent.clone(), running, stale));
     }
-    let ids = coord.job_queue.insert(|b| {
+    let ids = coord.job_queue.insert_job(|b| {
         start_nodes(b, &targets);
         Vec::new()
     })?;
@@ -269,7 +269,7 @@ pub async fn stop_many(
     for agent in agents {
         targets.push((agent.clone(), lifecycle::is_running(agent).await));
     }
-    let ids = coord.job_queue.insert(|b| {
+    let ids = coord.job_queue.insert_job(|b| {
         stop_nodes(b, &targets, graceful);
         Vec::new()
     })?;

hive-c0re/src/job_queue/tests.rs

@@ -21,7 +21,7 @@ use super::*;
 /// graph. A test that needs a handle calls `q.insert` directly and names the
 /// node it cares about.
 fn insert(q: &JobQueue, declare: impl FnOnce(&JobBuilder)) {
-    q.insert(|b| {
+    q.insert_job(|b| {
         declare(b);
         Vec::new()
     })