feat(#3245): gate rustdoc in nix flake check, and clear the workspace

Nothing in the gate read doc-comments: clippy doesn't check intra-doc
links, cargo test doesn't, and no check built docs. So a [`Foo`] pointing
at a renamed, moved or deleted item rendered as plain text and had no
discoverer but a human happening to read the comment.

That matters here more than in most repos, because the convention is to
put a thing's authoritative description in one doc-comment and point at
it from everywhere else -- the design leans on the pointers being real,
and a dangling link is worse than no link since it names something and
sends the reader looking.

Adds `docs-rustdoc` to nix/checks.nix: craneLib.cargoDoc over
--workspace --no-deps --document-private-items, denying six rustdoc
lints. Listed explicitly rather than -D warnings so a new lint appearing
upstream cannot red the build on a class nobody has triaged.

--document-private-items is load-bearing rather than thoroughness for
its own sake: most of this workspace's doc-comments live on private
items and //! module headers, so without it rustdoc checks a small
fraction of the links and the gate sits green while the rot continues.

Then fixes every error it reports, 40 to 0 across nine crates. The
classes differ and so do the fixes:

- public item, wrong scope -> qualify. Node and Node::parent are both
  public; the link failed only because scheduler.rs does not import
  Node. Six sites become [`crate::Node::parent`].
- private item -> downgrade to backticks. Nothing was made public to
  satisfy a lint; changing API surface to appease a doc check would be
  the tail wagging the dog.
- genuinely dead -> [`JobBuilder::insert_into`] names a method that does
  not exist. Insertion is Scheduler::insert_job.
- prose that looks like markup -> argv[0] parsed as a link, and
  <args>/<hex>/<name> parsed as HTML tags.

Note for future fixes: pub(crate) resolves in an intra-doc link, a plain
private fn in a binary crate does not (wait_for_nodes resolved,
connect_hint did not, same crate, same shape).

The check does not ride the clippy/test artifact cache. It takes
cargoArtifacts, but rustdoc needs its own flavour of dependency
metadata, which cargo build does not produce, so a --no-deps docs build
still compiles dependencies it never documents. Measured at 6m47s cold;
that reasoning is recorded in the check's own comment so the next reader
does not re-derive it.

Verified by running the check's exact command against the pre-cleanup
tree first: 40 errors, build failed. A gate that cannot fail is not
evidence, and building it before the cleanup makes that proof free.

hive-jobq/src/builder.rs

@@ -12,7 +12,7 @@
 //! inserted from outside this crate — `new()` and `insert_with` are both
 //! `pub(crate)`, and there is deliberately no `Default` impl, since a trait impl
 //! on a `pub` type is public regardless. There is no intermediate
-//! node-description type to keep in sync with [`crate::Graph::insert`]'s signature —
+//! node-description type to keep in sync with `Graph::insert`'s signature —
 //! so a job has no representation that can be passed around instead of being
 //! inserted.
 //!
@@ -115,7 +115,7 @@ pub enum BuildError {
 /// Reject a job whose own declarations don't hold up — **before anything is
 /// inserted**, so no failure can leave a partial job behind.
 ///
-/// This covers *every* rejection [`crate::Graph::insert`] can raise for a
+/// This covers *every* rejection `Graph::insert` can raise for a
 /// builder-produced node, which is what makes the insert loop below infallible
 /// in practice:
 ///
@@ -387,7 +387,7 @@ impl<N, R> From<&NodeRef<'_, N, R>> for NodeGuid {
 impl<N, R> NodeRef<'_, N, R> {
     /// This node's handle, for callers that want to hold the identity without
     /// the builder borrow (e.g. to look the id up after
-    /// [`JobBuilder::insert_into`]).
+    /// [`crate::scheduler::Scheduler::insert_job`]).
     #[must_use]
     pub fn guid(self) -> NodeGuid {
         self.guid

hive-jobq/src/lib.rs

@@ -321,7 +321,7 @@ pub struct Node<N, R> {
 /// An error from inserting into or loading a [`Graph`] with a dangling id.
 ///
 /// A [`NodeId`] is only meaningful against the graph that minted it, so both
-/// entry points — [`Graph::insert`] and deserialization — reject references to
+/// entry points — `Graph::insert` and deserialization — reject references to
 /// nodes the graph does not contain. That is what lets internal iteration trust
 /// every id the graph holds.
 #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
@@ -482,8 +482,8 @@ impl<N, R> Graph<N, R> {
     /// Insert without re-validating — **only** for a node the builder has
     /// already proved well-formed.
     ///
-    /// [`crate::builder::check_job_shape`] decides every rejection
-    /// [`Graph::insert`] could raise, before the first node lands. Re-checking
+    /// `check_job_shape` decides every rejection
+    /// `Graph::insert` could raise, before the first node lands. Re-checking
     /// here would not add safety: the insert loop mutates as it goes, so a
     /// rejection at node `i` would leave `0..i` in the graph — a loud error
     /// *after* the corruption rather than instead of it. Making the sink

hive-jobq/src/resources.rs

@@ -7,7 +7,7 @@
 //! available-once". Typical names: `build-slot` (capacity = number of build
 //! slots), `agent/<name>` (capacity 1 — the per-agent lifecycle lock).
 //!
-//! The one operation that matters is [`ResourceTable::try_acquire_all`]: it
+//! The one operation that matters is `ResourceTable::try_acquire_all`: it
 //! takes *all* of a node's resource requests and either grants every one or
 //! grants none, touching nothing on failure. Because a node acquires all its
 //! resources atomically at start (never holds one while waiting for another),
@@ -27,8 +27,8 @@ use std::hash::Hash;
 ///
 /// Configure known capacities with [`ResourceTable::set_capacity`]; any name
 /// left unconfigured has the default capacity (1). Acquire and release move
-/// units atomically via [`ResourceTable::try_acquire_all`] /
-/// [`ResourceTable::release_all`].
+/// units atomically via `ResourceTable::try_acquire_all` /
+/// `ResourceTable::release_all`.
 #[derive(Debug, Clone)]
 pub struct ResourceTable<R> {
     /// Configured capacities, keyed by resource. Missing ⇒ `default_capacity`.

hive-jobq/src/scheduler.rs

@@ -38,7 +38,7 @@ use crate::builder::{BuildError, JobBuilder, NodeGuid};
 use crate::resources::ResourceTable;
 use crate::{Dep, Graph, GraphError, NodeId, State, TerminalState};
 
-/// The result of a node's own execution, reported to [`Scheduler::complete`].
+/// The result of a node's own execution, reported to `Scheduler::complete`.
 ///
 /// `Cancelled` is not an outcome a runner reports — it is scheduler-driven (an
 /// `AfterOk` dependency failed), so a runner only ever says `Done` or `Failed`.
@@ -60,7 +60,7 @@ pub struct Scheduler<N, R: Clone + Eq + Hash> {
     resources: ResourceTable<R>,
     /// Fresh units each owner node acquired: `owner → [(resource, count)]`.
     /// Recorded against the node that *acquired* the units (never a borrower);
-    /// released back to the table once the owner and its whole [`Node::parent`]
+    /// released back to the table once the owner and its whole [`crate::Node::parent`]
     /// subtree are terminal.
     owned: HashMap<NodeId, Vec<(R, u32)>>,
     /// Which branch currently borrows a given owner's grant: `(owner, resource)
@@ -89,7 +89,7 @@ impl<N, R: Clone + Eq + Hash> Scheduler<N, R> {
     }
 
     /// Append a node under `parent` — e.g. a running node growing more work into
-    /// its own subtree. Delegates to [`Graph::insert`]; claim again afterwards
+    /// its own subtree. Delegates to `Graph::insert`; claim again afterwards
     /// to start it once it is runnable.
     ///
     /// # Errors
@@ -114,7 +114,7 @@ impl<N, R: Clone + Eq + Hash> Scheduler<N, R> {
     /// being passed around as a spec.
     ///
     /// The one insertion entry point for a job. Nodes go straight into
-    /// [`Graph::insert_unchecked`]: [`crate::builder::check_job_shape`] has
+    /// `Graph::insert_unchecked`: `check_job_shape` has
     /// already decided every rejection the graph could raise, so re-validating
     /// per node could only report a problem *after* the earlier nodes were
     /// inserted. Claim again afterwards to start whatever became runnable.
@@ -253,7 +253,7 @@ impl<N, R: Clone + Eq + Hash> Scheduler<N, R> {
         true
     }
 
-    /// The nearest [`Node::parent`] ancestor of `id` that *owns* (holds real
+    /// The nearest [`crate::Node::parent`] ancestor of `id` that *owns* (holds real
     /// units of) `name`, or `None` if none does (⇒ `id` must acquire it fresh).
     fn parent_ancestor_owning(&self, id: NodeId, name: &R) -> Option<NodeId> {
         let mut cur = self.graph.node(id).and_then(|n| n.parent);
@@ -266,7 +266,7 @@ impl<N, R: Clone + Eq + Hash> Scheduler<N, R> {
         None
     }
 
-    /// Whether `ancestor` lies on `id`'s [`Node::parent`] chain (i.e. `id` is in
+    /// Whether `ancestor` lies on `id`'s [`crate::Node::parent`] chain (i.e. `id` is in
     /// `ancestor`'s subtree). `id` itself does not count as its own ancestor.
     fn parent_chain_contains(&self, id: NodeId, ancestor: NodeId) -> bool {
         let mut cur = self.graph.node(id).and_then(|n| n.parent);
@@ -286,7 +286,7 @@ impl<N, R: Clone + Eq + Hash> Scheduler<N, R> {
             .is_some_and(|units| units.iter().any(|(n, _)| n == name))
     }
 
-    /// Whether `root` and every node in its [`Node::parent`] subtree are
+    /// Whether `root` and every node in its [`crate::Node::parent`] subtree are
     /// terminal — the condition for releasing `root`'s owned grants (and for
     /// giving back a borrow whose branch-root is `root`).
     fn subtree_terminal(&self, root: NodeId) -> bool {
@@ -298,7 +298,7 @@ impl<N, R: Clone + Eq + Hash> Scheduler<N, R> {
     }
 
     /// Report a running node's own logic result. On success the node is *not*
-    /// terminal until its sub-nodes ([`Node::parent`] children) all finish — it
+    /// terminal until its sub-nodes ([`crate::Node::parent`] children) all finish — it
     /// rests in [`State::Finishing`] until then, rolling up to [`State::Done`]
     /// (every child `Done`) or [`State::Failed`] (any child `Failed`/`Cancelled`).
     /// On failure it is `Failed` at once and its pending sub-nodes are cancelled
@@ -324,7 +324,7 @@ impl<N, R: Clone + Eq + Hash> Scheduler<N, R> {
         self.release_ready();
     }
 
-    /// [`Scheduler::complete`], plus whatever the node declared into the builder
+    /// `Scheduler::complete`, plus whatever the node declared into the builder
     /// it was handed while running.
     ///
     /// `grown`'s nodes are inserted **under `id`** and *before* the completion,
@@ -440,7 +440,7 @@ impl<N, R: Clone + Eq + Hash> Scheduler<N, R> {
     /// After `start` became terminal, roll up every ancestor that was parked in
     /// `Finishing` awaiting its children: once all of an ancestor's children are
     /// terminal it transitions (Done / Failed), which may let *its* parent roll
-    /// up too, and so on up the [`Node::parent`] chain.
+    /// up too, and so on up the [`crate::Node::parent`] chain.
     fn roll_up_ancestors(&mut self, start: NodeId) {
         let mut cur = self.graph.node(start).and_then(|n| n.parent);
         while let Some(a) = cur {