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.

nix/checks.nix

@@ -64,6 +64,53 @@ in
     HIVE_ASSETS_DIR = "${self.packages.${system}.assets}/share/hyperhive";
   };
 
+  # Rustdoc gate. Builds the workspace's docs and turns rustdoc's own
+  # lints into hard failures, so a `[`Foo`]` pointing at a renamed,
+  # moved or deleted item reds the PR instead of silently rendering as
+  # plain text.
+  #
+  # Why this needs to exist at all: nothing else reads doc-comments.
+  # Clippy doesn't check intra-doc links, `cargo test` doesn't, and no
+  # other check builds docs — so a dangling pointer had no discoverer
+  # but a human happening to read the comment. That matters more here
+  # than in most repos, because the convention is to put a thing's
+  # authoritative description in one doc-comment and link to 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
+  # so sends the reader looking.
+  #
+  # `--document-private-items` is load-bearing, not thoroughness for its
+  # own sake: most of this workspace's doc-comments live on private
+  # items and `//!` module headers. Without it rustdoc checks a small
+  # fraction of the links and the gate would sit green while the rot
+  # continued.
+  #
+  # ⚠️ This does NOT reuse the `cargoArtifacts` the way `clippy` and
+  # `cargo-test` do — it takes them, 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 will never
+  # document (matrix-sdk dominates), and this check costs its own build
+  # rather than riding the others' cache.
+  docs-rustdoc = craneLib.cargoDoc {
+    src = cleanSrc;
+    inherit cargoArtifacts nativeBuildInputs;
+    pname = "hyperhive-workspace";
+    version = "0.1.0";
+    cargoDocExtraArgs = "--workspace --no-deps --document-private-items";
+    # Every rustdoc lint that catches a *wrong* doc, denied. Kept as an
+    # explicit list rather than a blanket `-D warnings` so that adding a
+    # new rustdoc lint upstream can't silently red the build on a class
+    # nobody has triaged yet.
+    RUSTDOCFLAGS = builtins.concatStringsSep " " [
+      "-D rustdoc::broken_intra_doc_links"
+      "-D rustdoc::private_intra_doc_links"
+      "-D rustdoc::invalid_html_tags"
+      "-D rustdoc::redundant_explicit_links"
+      "-D rustdoc::bare_urls"
+      "-D rustdoc::unescaped_backticks"
+    ];
+  };
+
   # Nix options docs evaluation. Cheap: pulls in `nixosOptionsDoc` +
   # the host module's stub eval, no rust or frontend deps. CI fails
   # fast if a module change breaks option declarations or the doc