peat_mesh/hierarchy/
mod.rs

1//! Flexible hierarchy and role management for mesh topology
2//!
3//! This module provides pluggable hierarchy strategies that enable both
4//! static (organizational) and dynamic (capability-based) role assignment.
5
6mod dynamic_strategy;
7mod hybrid_strategy;
8mod static_strategy;
9
10pub use dynamic_strategy::{DynamicHierarchyStrategy, ElectionConfig, ElectionWeights};
11pub use hybrid_strategy::HybridHierarchyStrategy;
12pub use static_strategy::StaticHierarchyStrategy;
13
14use crate::beacon::{GeographicBeacon, HierarchyLevel, NodeProfile};
15
16/// Node role within its hierarchy level
17#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
18pub enum NodeRole {
19    /// Leader: Coordinates peers at same level
20    Leader,
21    /// Member: Reports to leader at same level
22    Member,
23    /// Standalone: No same-level coordination
24    #[default]
25    Standalone,
26}
27
28/// Hierarchy strategy trait for pluggable role/level assignment
29///
30/// Integrators implement this trait to define how nodes determine their
31/// hierarchy level and role within the mesh. The protocol provides built-in
32/// strategies for common use cases:
33///
34/// - **StaticHierarchyStrategy**: Fixed assignment from configuration
35/// - **DynamicHierarchyStrategy**: Capability-based election
36/// - **HybridHierarchyStrategy**: Static baseline with dynamic transitions
37///
38/// # Example
39///
40/// ```ignore
41/// use peat_mesh::hierarchy::{HierarchyStrategy, StaticHierarchyStrategy, NodeRole};
42///
43/// let strategy = StaticHierarchyStrategy {
44///     assigned_level: HierarchyLevel::Squad,
45///     assigned_role: NodeRole::Leader,
46/// };
47///
48/// let level = strategy.determine_level(&node_profile);
49/// let role = strategy.determine_role(&node_profile, &nearby_beacons);
50/// ```
51pub trait HierarchyStrategy: Send + Sync + std::fmt::Debug {
52    /// Determine this node's hierarchy level
53    ///
54    /// # Arguments
55    ///
56    /// * `node_profile` - This node's capabilities and configuration
57    ///
58    /// # Returns
59    ///
60    /// The hierarchy level this node should operate at
61    fn determine_level(&self, node_profile: &NodeProfile) -> HierarchyLevel;
62
63    /// Determine this node's role within its level
64    ///
65    /// # Arguments
66    ///
67    /// * `node_profile` - This node's capabilities and configuration
68    /// * `nearby_peers` - Nearby beacons from peer discovery
69    ///
70    /// # Returns
71    ///
72    /// The role this node should assume (Leader, Member, or Standalone)
73    fn determine_role(
74        &self,
75        node_profile: &NodeProfile,
76        nearby_peers: &[GeographicBeacon],
77    ) -> NodeRole;
78
79    /// Check if this node can transition to a different level
80    ///
81    /// # Arguments
82    ///
83    /// * `current_level` - Current hierarchy level
84    /// * `new_level` - Proposed new hierarchy level
85    ///
86    /// # Returns
87    ///
88    /// `true` if transition is allowed, `false` otherwise
89    fn can_transition(&self, current_level: HierarchyLevel, new_level: HierarchyLevel) -> bool;
90}
peat_mesh/hierarchy/mod.rs

peat_mesh/hierarchy/
mod.rs
