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>> {