peat-protocol 0.9.0-rc.7

Peat Coordination Protocol — hierarchical capability composition over CRDTs for heterogeneous mesh networks
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

//! # Hierarchical Command Coordination
//!
//! This module implements bidirectional command dissemination with policy-based flexibility.
//!
//! ## Overview
//!
//! Complements upward capability aggregation with downward command propagation:
//! - **Policy-based routing**: Commands carry routing policies (buffer, conflict, acknowledgment)
//! - **Hierarchical dissemination**: Commands flow down through Zone → Cell → Node hierarchy
//! - **Acknowledgment tracking**: Optional acknowledgment based on command policy
//! - **Conflict resolution**: Deterministic resolution when multiple commands target same resource
//!
//! ## Architecture
//!
//! ```text
//! ┌──────────────────────────────────────────────────┐
//! │  Zone Commander (Higher Echelon)                │
//! │  Issues HierarchicalCommand with policies       │
//! └────────────────────┬─────────────────────────────┘
//!                      │
//!           ┌──────────┴──────────┐
//!           ▼                     ▼
//!    ┌─────────────┐       ┌─────────────┐
//!    │  Cell 1     │       │  Cell 2     │
//!    │  Receives   │       │  Receives   │
//!    │  & Routes   │       │  & Routes   │
//!    └──────┬──────┘       └──────┬──────┘
//!           │                     │
//!      ┌────┴────┐           ┌────┴────┐
//!      ▼         ▼           ▼         ▼
//!   Node-1   Node-2      Node-3   Node-4
//!   (Execute & Ack)     (Execute & Ack)
//! ```
//!
//! ## Usage
//!
//! ```rust,ignore
//! use peat_protocol::command::CommandCoordinator;
//! use peat_schema::command::v1::HierarchicalCommand;
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! // Create coordinator for a squad leader
//! let coordinator = CommandCoordinator::new(
//!     Some("squad-alpha".to_string()),
//!     "node-1".to_string(),
//!     vec!["node-1".to_string(), "node-2".to_string()], // squad members
//! );
//!
//! // Issue a command to squad members
//! let command = HierarchicalCommand {
//!     command_id: "cmd-001".to_string(),
//!     originator_id: "node-1".to_string(),
//!     // ... command details
//!     ..Default::default()
//! };
//!
//! coordinator.issue_command(command).await?;
//! # Ok(())
//! # }
//! ```
//!
//! ## Related ADRs
//!
//! - ADR-014: Distributed Coordination Primitives
//! - ADR-013: AI Operations and Binary Transfer
//! - ADR-009: Bidirectional Hierarchical Flows

mod conflict_resolver;
mod coordinator;
mod policy_impl; // Conflictable implementation for HierarchicalCommand
mod routing;
mod storage_trait;
mod timeout_manager;

pub use conflict_resolver::{ConflictResolver, ConflictResult};
pub use coordinator::CommandCoordinator;
pub use routing::{CommandRouter, TargetResolution};
pub use storage_trait::{CommandStorage, ObserverHandle};
pub use timeout_manager::{AckTimeout, TimeoutManager};

#[cfg(test)]
mod tests {
    #[test]
    fn test_command_module_accessible() {
        // Verify module compiles and types are accessible
        let _node_id = "test-node".to_string();
        // Module compiles successfully
    }
}