docs(runtime): clarify semantics of internal NodeId and PatchTrace fields

Author: kervel

src/runtime/src/diff.rs

@@ -237,8 +237,14 @@ pub fn diff(source: &LinkMLValue, target: &LinkMLValue, treat_missing_as_null: b
 
 #[derive(Debug, Clone, Default)]
 pub struct PatchTrace {
+    /// Node IDs of subtrees that were newly created by the patch.
+    ///
+    /// See [`crate::NodeId`] for semantics: these are internal, ephemeral IDs
+    /// that are useful for tooling and provenance, not object identifiers.
     pub added: Vec<NodeId>,
+    /// Node IDs of subtrees that were removed by the patch.
     pub deleted: Vec<NodeId>,
+    /// Node IDs of nodes that were directly updated (e.g., parent containers, scalars).
     pub updated: Vec<NodeId>,
 }
 

src/runtime/src/lib.rs

@@ -91,7 +91,18 @@ pub enum LinkMLValue {
     },
 }
 
-// Stable node identifiers assigned to every LinkMLValue node
+/// Internal node identifier used for provenance and update tracking.
+///
+/// Node IDs are assigned to every `LinkMLValue` node when values are constructed or
+/// transformed. They exist solely as technical identifiers to help with patching and
+/// provenance (for example, `PatchTrace.added`/`deleted` collect `NodeId`s of affected
+/// subtrees). They are not intended to identify domain objects — for that, use LinkML
+/// identifier or key slots as defined in the schema.
+///
+/// Important properties:
+/// - Local and ephemeral: loading the same data twice will yield different `NodeId`s.
+/// - Non-persistent: never serialize or expose as a model identifier.
+/// - Useful for tracking modifications within a single in-memory value.
 pub type NodeId = u64;
 
 static NEXT_NODE_ID: AtomicU64 = AtomicU64::new(1);
@@ -101,6 +112,10 @@ fn new_node_id() -> NodeId {
 }
 
 impl LinkMLValue {
+    /// Returns the internal [`NodeId`] of this node.
+    ///
+    /// This ID is only for internal provenance/update tracking and is not a
+    /// semantic identifier of the represented object.
     pub fn node_id(&self) -> NodeId {
         match self {
             LinkMLValue::Scalar { node_id, .. }