peat_protocol/command/mod.rs
1//! # Hierarchical Command Coordination
2//!
3//! This module implements bidirectional command dissemination with policy-based flexibility.
4//!
5//! ## Overview
6//!
7//! Complements upward capability aggregation with downward command propagation:
8//! - **Policy-based routing**: Commands carry routing policies (buffer, conflict, acknowledgment)
9//! - **Hierarchical dissemination**: Commands flow down through Zone → Cell → Node hierarchy
10//! - **Acknowledgment tracking**: Optional acknowledgment based on command policy
11//! - **Conflict resolution**: Deterministic resolution when multiple commands target same resource
12//!
13//! ## Architecture
14//!
15//! ```text
16//! ┌──────────────────────────────────────────────────┐
17//! │ Zone Commander (Higher Echelon) │
18//! │ Issues HierarchicalCommand with policies │
19//! └────────────────────┬─────────────────────────────┘
20//! │
21//! ┌──────────┴──────────┐
22//! ▼ ▼
23//! ┌─────────────┐ ┌─────────────┐
24//! │ Cell 1 │ │ Cell 2 │
25//! │ Receives │ │ Receives │
26//! │ & Routes │ │ & Routes │
27//! └──────┬──────┘ └──────┬──────┘
28//! │ │
29//! ┌────┴────┐ ┌────┴────┐
30//! ▼ ▼ ▼ ▼
31//! Node-1 Node-2 Node-3 Node-4
32//! (Execute & Ack) (Execute & Ack)
33//! ```
34//!
35//! ## Usage
36//!
37//! ```rust,ignore
38//! use peat_protocol::command::CommandCoordinator;
39//! use peat_schema::command::v1::HierarchicalCommand;
40//!
41//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
42//! // Create coordinator for a squad leader
43//! let coordinator = CommandCoordinator::new(
44//! Some("squad-alpha".to_string()),
45//! "node-1".to_string(),
46//! vec!["node-1".to_string(), "node-2".to_string()], // squad members
47//! );
48//!
49//! // Issue a command to squad members
50//! let command = HierarchicalCommand {
51//! command_id: "cmd-001".to_string(),
52//! originator_id: "node-1".to_string(),
53//! // ... command details
54//! ..Default::default()
55//! };
56//!
57//! coordinator.issue_command(command).await?;
58//! # Ok(())
59//! # }
60//! ```
61//!
62//! ## Related ADRs
63//!
64//! - ADR-014: Distributed Coordination Primitives
65//! - ADR-013: AI Operations and Binary Transfer
66//! - ADR-009: Bidirectional Hierarchical Flows
67
68mod conflict_resolver;
69mod coordinator;
70mod policy_impl; // Conflictable implementation for HierarchicalCommand
71mod routing;
72mod storage_trait;
73mod timeout_manager;
74
75pub use conflict_resolver::{ConflictResolver, ConflictResult};
76pub use coordinator::CommandCoordinator;
77pub use routing::{CommandRouter, TargetResolution};
78pub use storage_trait::{CommandStorage, ObserverHandle};
79pub use timeout_manager::{AckTimeout, TimeoutManager};
80
81#[cfg(test)]
82mod tests {
83 #[test]
84 fn test_command_module_accessible() {
85 // Verify module compiles and types are accessible
86 let _node_id = "test-node".to_string();
87 // Module compiles successfully
88 }
89}