job_queue: trim NodeKind/Resource doc comments now that coordinator.md covers them

hive-c0re/src/job_queue/resource.rs

@@ -15,46 +15,21 @@
 //! the meta window) cannot deadlock against each other.
 
 /// The two resource classes the queue gates concurrency on, as the crate's
-/// generic resource type `R`.
+/// generic resource type `R`. What each holds, who declares it, and the
+/// exemptions: see `docs/scheduler/coordinator.md`'s _Scheduler semantics_
+/// (build slots, the per-agent lease) and _Two further layers protect the
+/// meta repo_ (the deploy window) sections — this enum stays the one-line
+/// summary, not a second copy.
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum Resource {
     /// One of the `buildSlots` permits, held by a nix-heavy node for its
-    /// duration. Capacity is `services.hyperhive.c0re.buildSlots` (default 1),
-    /// set on the [`hive_jobq::resources::ResourceTable`] at construction.
+    /// duration.
     BuildSlot,
-    /// The per-agent lifecycle lease — globally exclusive per agent across all
-    /// DAGs (unconfigured, so the crate's default capacity 1 applies). Held by
-    /// a DAG's first container-affecting node for that agent and re-entered by
-    /// the rest of that agent's subtree via the crate's recursive lock, so two
-    /// DAGs never interleave container ops on one agent.
-    ///
-    /// Nodes that touch the *store or meta repo* rather than the running
-    /// container do not declare it — `MetaSync`, `Prebuild`, `Provision`,
-    /// `MetaLock`, `WritePermFile`, `Reparent`. That exemption is what lets a
-    /// `Prebuild` overlap another DAG's work on the same agent. `Provision`
-    /// precedes the container's existence entirely, so the lease is first taken
-    /// at the `Create` it feeds.
+    /// The per-agent lifecycle lease — globally exclusive per agent across
+    /// all DAGs.
     Agent(String),
-    /// The meta-repo mutation window — a global singleton (default capacity 1)
-    /// held by any node that mutates the meta repo, so two meta mutations never
-    /// interleave. That exclusion is load-bearing: a commit landing inside
-    /// another node's staged `prepare_deploy`→`finalize_deploy` window would
-    /// sweep the staged `flake.lock` into its own commit and neuter
-    /// `abort_deploy`. Replaces the former runtime `meta::exclusive()` mutex: a
-    /// `MutexGuard` cannot span scheduler nodes, but a resource held by a
-    /// subtree root *can* — which is what lets the two-phase deploy
-    /// (`prepare_deploy` stages `flake.lock` uncommitted across the whole
-    /// container build, `finalize_deploy`/`abort_deploy` resolve it) be
-    /// decomposed into sub-nodes instead of one opaque node. Descendants of a
-    /// holder re-enter it through the crate's recursive lock, exactly like
-    /// [`Resource::Agent`].
-    ///
-    /// Deliberately **not** declared by `Prebuild`: the window must stay off the
-    /// multi-minute toplevel build, which only *reads* the store. Holding a
-    /// hive-global cap-1 across it would serialize every agent's rebuild behind
-    /// every other's — which is why the meta preamble is its own `MetaSync`
-    /// node, and a sibling of `Prebuild` rather than its parent (a resource is
-    /// held across the holder's whole subtree).
+    /// The meta-repo mutation window — a global singleton held by any node
+    /// that mutates the meta repo, so two meta mutations never interleave.
     MetaWindow,
 }