diff --git a/hive-jobq/src/lib.rs b/hive-jobq/src/lib.rs
index b63e125c..4420362b 100644
--- a/hive-jobq/src/lib.rs
+++ b/hive-jobq/src/lib.rs
@@ -36,10 +36,14 @@
 /// is deliberately *not* encoded in the id, so the id never changes as the tree
 /// grows or collapses. The hierarchical `1/1/2` path used in the UI is derived
 /// from the parent tree at render time.
+///
+/// The inner field is crate-private: an id can only originate from the graph's
+/// monotonic counter (or deserialization of a persisted graph), never be
+/// fabricated by a caller — that is what makes it opaque.
 #[derive(
     Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, serde::Serialize, serde::Deserialize,
 )]
-pub struct NodeId(pub u64);
+pub struct NodeId(pub(crate) u64);
 
 /// A named counting semaphore.
 ///