Clarify tree protocol runtime and routing

Document the hook lifecycle, ingress rules, and longest-prefix routing behavior so the tree endpoint code is easier to follow. Keep the pass behavior-neutral while tightening local names and comments around non-obvious protocol paths.

src/protocol/tree/hook.rs

@@ -1,15 +1,25 @@
 //! Hook state for pending and active protocol flows.
+//!
+//! Hooks move through two phases:
+//! - `PendingHook` tracks enough context to attribute faults before the callee accepts.
+//! - `ActiveHook` tracks the live bidirectional flow after activation.
+//!
+//! The table indexes active hooks both by their host-side return path and by the remote
+//! peer path so routing code can resolve whichever side of the relationship it currently has.
 
 use alloc::{collections::BTreeMap, string::String, vec::Vec};
 
 /// Hook table key scoped to the hook host path.
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub struct HookKey {
+    /// Path of the endpoint hosting the hook state.
     pub return_path: Vec<String>,
+    /// Per-host hook identifier.
     pub hook_id: u64,
 }
 
 impl HookKey {
+    /// Builds the canonical key for a hook hosted at `return_path`.
     #[must_use]
     pub fn new(return_path: Vec<String>, hook_id: u64) -> Self {
         Self {
@@ -22,22 +32,34 @@ impl HookKey {
 /// Pending hook context used only for fault attribution before activation.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PendingHook {
+    /// Path of the endpoint hosting the pending hook.
     pub return_path: Vec<String>,
+    /// Per-host hook identifier.
     pub hook_id: u64,
+    /// Caller path to promote into `peer_path` once the hook becomes active.
     pub caller_src_path: Vec<String>,
+    /// Procedure that created the hook.
     pub procedure_id: String,
+    /// Optional destination leaf inside the peer endpoint.
     pub dst_leaf: Option<String>,
 }
 
 /// Active hook context used for ordinary data traffic.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ActiveHook {
+    /// Path of the endpoint hosting the active hook.
     pub return_path: Vec<String>,
+    /// Per-host hook identifier.
     pub hook_id: u64,
+    /// Remote endpoint path currently paired with this hook.
     pub peer_path: Vec<String>,
+    /// Procedure that owns the hook conversation.
     pub procedure_id: String,
+    /// Optional destination leaf inside the peer endpoint.
     pub dst_leaf: Option<String>,
+    /// Set once the local side has emitted its terminal message.
     pub local_ended: bool,
+    /// Set once the peer side has emitted its terminal message.
     pub peer_ended: bool,
 }
 
@@ -55,6 +77,10 @@ pub struct HookTable {
 }
 
 impl HookTable {
+    /// Allocates a non-zero hook id for a hook hosted at `return_path`.
+    ///
+    /// Hook ids are scoped by host path, so this only needs to guarantee uniqueness within the
+    /// local table. The wrapped increment keeps allocation infallible for long-lived runtimes.
     #[must_use]
     pub fn allocate_hook_id(&mut self, _return_path: &[String]) -> u64 {
         let id = self.next_id.max(1);
@@ -62,6 +88,7 @@ impl HookTable {
         id
     }
 
+    /// Inserts a hook that has been announced but not yet accepted by the callee.
     pub fn insert_pending(&mut self, pending: PendingHook) -> Result<(), HookConflict> {
         let key = HookKey::new(pending.return_path.clone(), pending.hook_id);
         if self.pending.contains_key(&key) || self.active.contains_key(&key) {
@@ -71,6 +98,10 @@ impl HookTable {
         Ok(())
     }
 
+    /// Promotes a pending hook into the active table.
+    ///
+    /// Activation intentionally reuses the original hook id and host path, but swaps the
+    /// pending caller attribution into the active peer path used for data routing.
     pub fn activate_pending(&mut self, key: &HookKey) -> Option<()> {
         let pending = self.pending.remove(key)?;
         self.insert_active(ActiveHook {
@@ -86,6 +117,7 @@ impl HookTable {
         Some(())
     }
 
+    /// Inserts a live hook and its peer-path lookup entry.
     pub fn insert_active(&mut self, active: ActiveHook) -> Result<(), HookConflict> {
         let key = HookKey::new(active.return_path.clone(), active.hook_id);
         if self.pending.contains_key(&key)
@@ -105,10 +137,12 @@ impl HookTable {
         Ok(())
     }
 
+    /// Removes a pending hook without affecting active state.
     pub fn remove_pending(&mut self, key: &HookKey) -> Option<PendingHook> {
         self.pending.remove(key)
     }
 
+    /// Removes an active hook and its secondary peer-path index entry.
     pub fn remove_active(&mut self, key: &HookKey) -> Option<ActiveHook> {
         let active = self.active.remove(key)?;
         if let Some(peer_paths) = self.active_by_peer.get_mut(&active.hook_id) {
@@ -120,20 +154,28 @@ impl HookTable {
         Some(active)
     }
 
+    /// Returns the pending hook for `key`, if present.
     #[must_use]
     pub fn pending(&self, key: &HookKey) -> Option<&PendingHook> {
         self.pending.get(key)
     }
 
+    /// Returns the active hook for `key`, if present.
     #[must_use]
     pub fn active(&self, key: &HookKey) -> Option<&ActiveHook> {
         self.active.get(key)
     }
 
+    /// Returns the mutable active hook for `key`, if present.
     pub fn active_mut(&mut self, key: &HookKey) -> Option<&mut ActiveHook> {
         self.active.get_mut(key)
     }
 
+    /// Resolves an active hook from either side of the conversation.
+    ///
+    /// The host side addresses hooks directly by `(return_path, hook_id)`. Peer-originated
+    /// traffic only has `(hook_id, peer_path)`, so the secondary index maps that back to the
+    /// canonical host-scoped key.
     #[must_use]
     pub fn resolve_active_key(
         &self,
@@ -148,6 +190,7 @@ impl HookTable {
         self.active_by_peer.get(&hook_id)?.get(peer_path).cloned()
     }
 
+    /// Marks the local side finished and returns `true` once both sides are finished.
     pub fn mark_local_end(&mut self, key: &HookKey) -> bool {
         let Some(active) = self.active_mut(key) else {
             return false;
@@ -156,6 +199,7 @@ impl HookTable {
         active.peer_ended
     }
 
+    /// Marks the peer side finished and returns `true` once both sides are finished.
     pub fn mark_peer_end(&mut self, key: &HookKey) -> bool {
         let Some(active) = self.active_mut(key) else {
             return false;
@@ -164,11 +208,13 @@ impl HookTable {
         active.local_ended
     }
 
+    /// Returns the number of active hooks.
     #[must_use]
     pub fn active_len(&self) -> usize {
         self.active.len()
     }
 
+    /// Returns the number of pending hooks.
     #[must_use]
     pub fn pending_len(&self) -> usize {
         self.pending.len()