nornir 0.4.13

Companion to cargo: dependency tracking, release gating, deploy, benchmarks, and documentation assembly. Project-agnostic.
Documentation 
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
90
91
92
93
94
95
96
97
98
99
100

//! Topological-sort dispatcher: "what should I work on next?"
//!
//! The single function the rest of the world (CLI, MCP, agents) calls
//! is [`topo_ready`]. It returns every node that:
//!   - belongs to a plan whose status is `Active` (or `Draft` —
//!     drafts are work-in-progress, not archived),
//!   - has status `Pending` or `Ready`,
//!   - has all incoming-edge dependencies satisfied (every `from`
//!     node has status `Done`),
//!
//! …in topological order so dependents always come after dependencies.
//! The returned [`NextStep`] carries everything an actor needs to
//! decide "should I take this?".

use std::collections::BTreeMap;

use petgraph::algo::toposort;
use petgraph::graph::{DiGraph, NodeIndex};

use super::event::{NodeStatus, PlanStatus};
use super::ids::{NodeId, PlanId};
use super::state::Funnel;

#[derive(Debug, Clone, serde::Serialize)]
pub struct NextStep {
    pub plan_id: PlanId,
    pub node_id: NodeId,
    pub kind: String,
    pub targets: Vec<String>,
    pub summary: String,
    pub prompt_excerpt: Option<String>,
}

/// Return every actionable node across every active plan, in
/// topological order. Side-effect: promotes eligible `Pending` nodes
/// to `Ready` in-memory (no event emitted — the readiness derivation
/// is deterministic from edges + statuses, so emitting events would
/// just bloat the log).
pub fn topo_ready(funnel: &mut Funnel) -> Vec<NextStep> {
    funnel.promote_ready();

    let mut out: Vec<NextStep> = Vec::new();
    for plan in funnel.plans.values() {
        if !matches!(plan.status, PlanStatus::Draft | PlanStatus::Active) {
            continue;
        }

        let mut graph: DiGraph<NodeId, ()> = DiGraph::new();
        let mut idx: BTreeMap<NodeId, NodeIndex> = BTreeMap::new();
        for id in plan.nodes.keys() {
            idx.insert(id.clone(), graph.add_node(id.clone()));
        }
        for (from, to) in &plan.edges {
            if let (Some(&a), Some(&b)) = (idx.get(from), idx.get(to)) {
                graph.add_edge(a, b, ());
            }
        }

        let order = match toposort(&graph, None) {
            Ok(o) => o,
            Err(cyc) => {
                eprintln!(
                    "funnel: plan `{}` has a cycle around node `{}` — skipping",
                    plan.id,
                    graph[cyc.node_id()]
                );
                continue;
            }
        };

        for ni in order {
            let nid = &graph[ni];
            let node = &plan.nodes[nid];
            if matches!(node.status, NodeStatus::Ready | NodeStatus::Pending) {
                // Only Ready is genuinely actionable; surface
                // Pending too so callers can see *why* nothing
                // ran (deps not done).
                if node.status == NodeStatus::Ready {
                    out.push(NextStep {
                        plan_id: plan.id.clone(),
                        node_id: nid.clone(),
                        kind: node.kind.clone(),
                        targets: node.targets.clone(),
                        summary: plan.summary.clone(),
                        prompt_excerpt: node.prompt_excerpt.clone(),
                    });
                }
            }
        }
    }
    out
}

/// Like [`topo_ready`] but scoped to a specific plan.
pub fn topo_ready_for_plan(funnel: &mut Funnel, plan_id: &PlanId) -> Vec<NextStep> {
    topo_ready(funnel)
        .into_iter()
        .filter(|s| &s.plan_id == plan_id)
        .collect()
}