From 377dbb57e3d9451b57f6b899b2060329a63602a8 Mon Sep 17 00:00:00 2001
From: damocles <damocles@hyperhive.local>
Date: Wed, 19 Aug 2026 21:06:16 +0200
Subject: [PATCH] swarm-controller: fix broken intra-doc links (private items,
 rustdoc lint)

---
 swarm-controller/src/config_pr.rs | 10 ++++++++--
 swarm-controller/src/forge.rs     |  7 ++++---
 swarm-controller/src/main.rs      | 11 ++++++-----
 3 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/swarm-controller/src/config_pr.rs b/swarm-controller/src/config_pr.rs
index 9cdd0590..a94c7da7 100644
--- a/swarm-controller/src/config_pr.rs
+++ b/swarm-controller/src/config_pr.rs
@@ -16,7 +16,7 @@
 //! - [`ConfigPrCache::apply_webhook_delivery`] — called from
 //!   `crate::webhook::post_webhook_forge` on a verified `ConfigPr` delivery.
 //!   The low-latency path: a PR opening or closing shows up immediately
-//!   instead of waiting up to [`POLL_INTERVAL`].
+//!   instead of waiting up to `POLL_INTERVAL`.
 //!
 //! Per mara's review call: ship both from the start rather than the poll
 //! alone — the eventual swarm-level replacement for `hive-c0re`'s own
@@ -93,6 +93,12 @@ impl ConfigPrCache {
             .cloned()
     }
 
+    /// ⚠️ Can race [`Self::apply_webhook_delivery`]: a scan started before a
+    /// PR opened may finish *after* the webhook already upserted it, and
+    /// this snapshot — taken before that PR existed — will overwrite the
+    /// fresh entry. Self-heals within one `POLL_INTERVAL` (the next scan
+    /// sees the PR), so not worth coordinating against; noted per argus's
+    /// review rather than left implicit.
     fn replace(&self, scan: HashMap<String, ConfigPrStatus>) {
         *self
             .0
@@ -152,7 +158,7 @@ impl ConfigPrCache {
 ///
 /// The scan runs immediately on the first tick (`tokio::time::interval`'s
 /// default), so the cache is populated on startup rather than staying empty
-/// for a full [`POLL_INTERVAL`] after boot.
+/// for a full `POLL_INTERVAL` after boot.
 pub fn spawn(client: Arc<Client>) -> Arc<ConfigPrCache> {
     let cache = Arc::new(ConfigPrCache::new());
     let cache_for_task = Arc::clone(&cache);
diff --git a/swarm-controller/src/forge.rs b/swarm-controller/src/forge.rs
index 897d7640..d2f8c3e0 100644
--- a/swarm-controller/src/forge.rs
+++ b/swarm-controller/src/forge.rs
@@ -31,7 +31,7 @@ use utoipa::ToSchema;
 use crate::webhook::DeliveryKind;
 
 /// An agent's open config-PR, as [`Client::list_open_config_prs`] reports it
-/// and [`crate::get_agent_config_pr`] serves it.
+/// and `GET /api/agents/{name}/config-pr` serves it.
 #[derive(Clone, Debug, PartialEq, Serialize, ToSchema)]
 pub struct ConfigPrStatus {
     pub pr_number: u64,
@@ -367,8 +367,9 @@ impl Client {
     /// name. Mirrors `hive-c0re::forge::config_pr_poll::poll_open_config_prs`'s
     /// scan shape (list repos in the org, list open PRs per repo) but returns
     /// data instead of side-effecting an approval queue — this daemon has no
-    /// approval system of its own; it exists so [`crate::get_agent_config_pr`]
-    /// has something to answer from, independent of any one hive being up.
+    /// approval system of its own; it exists so `GET
+    /// /api/agents/{name}/config-pr` has something to answer from,
+    /// independent of any one hive being up.
     ///
     /// A single repo's list failing does not fail the whole scan — logged and
     /// skipped, so one flaky repo can't blank out every other agent's status.
diff --git a/swarm-controller/src/main.rs b/swarm-controller/src/main.rs
index b20deba1..a9a578aa 100644
--- a/swarm-controller/src/main.rs
+++ b/swarm-controller/src/main.rs
@@ -772,15 +772,16 @@ async fn get_jobq_rollup(State(state): State<AppState>) -> Json<Vec<hive_jobq_wi
 
 /// `agent`'s open config PR, from [`config_pr::ConfigPrCache`] — kept
 /// current by a webhook nudge (near-real-time) backstopped by a periodic
-/// scan (worst case: up to one [`config_pr::POLL_INTERVAL`] stale if a
+/// scan (worst case: up to one `config_pr::POLL_INTERVAL` stale if a
 /// delivery was ever missed). Not a live forge read either way, so this
 /// answers even when the forge itself is momentarily unreachable.
 ///
 /// `200` with a `null` body means "no open PR" (or "no scan has completed
-/// yet") — not distinguished, for the same reason [`ConfigPrCache::get`]
-/// doesn't: both read as "nothing to show" to the swarm-ui config-PR panel
-/// this feeds, and a cache is a best-effort read, not a source of truth
-/// callers should expect to disambiguate against.
+/// yet") — not distinguished, for the same reason
+/// [`config_pr::ConfigPrCache::get`] doesn't: both read as "nothing to show"
+/// to the swarm-ui config-PR panel this feeds, and a cache is a best-effort
+/// read, not a source of truth callers should expect to disambiguate
+/// against.
 #[utoipa::path(
     get,
     path = "/api/agents/{name}/config-pr",