Struct TaskGraph

Source

pub struct TaskGraph {
    pub goal: String,
    pub hitl_mode: HitlMode,
    pub nodes: HashMap<NodeId, TaskNode>,
}

Expand description

A validated directed acyclic graph of TaskNodes.

Produced by the director agent via crate::domain::council::events::CouncilEvent::PlanProposed and executed by the orchestrator runner in topological order.

§Construction

Prefer TaskGraph::new over direct struct construction to get automatic validation. Deserializing from a director’s JSON response should be followed by TaskGraph::validate_acyclic to re-check invariants.

§Concurrency model

The executor calls TaskGraph::ready_nodes after each node completes to discover newly-eligible nodes, which it launches concurrently.

§Example

use gglib_core::domain::council::task_graph::{TaskGraph, TaskNode, TaskNodeKind, NodeId, NodeStatus, HitlMode};

let nodes = vec![TaskNode {
    id: NodeId("only".into()),
    goal: "Do the thing".into(),
    depends_on: vec![],
    tool_allowlist: vec![],
    kind: TaskNodeKind::Leaf,
    role: None,
    status: NodeStatus::Pending,
    output: None,
    compacted_output: None,
    error: None,
}];
let g = TaskGraph::new("My goal".into(), HitlMode::None, nodes).unwrap();
assert_eq!(g.roots().len(), 1);

Fields§

§goal: String

The high-level goal the director is trying to achieve.

§hitl_mode: HitlMode

Human-in-the-loop approval policy for this execution run.

§nodes: HashMap<NodeId, TaskNode>

All work units, keyed by their unique NodeId.

Implementations§

Source §

impl TaskGraph

Source

pub fn new( goal: String, hitl_mode: HitlMode, nodes: Vec<TaskNode>, ) -> Result<Self, TaskGraphError>

Construct and validate a TaskGraph from a flat list of nodes.

Returns an error if the node list violates any structural invariant (duplicate ids, unknown dependencies, cycles, size/depth limits).

§Example

use gglib_core::domain::council::task_graph::{
    TaskGraph, TaskNode, TaskNodeKind, NodeId, NodeStatus, HitlMode,
};

let nodes = vec![TaskNode {
    id: NodeId("only".into()),
    goal: "Do the thing".into(),
    depends_on: vec![],
    tool_allowlist: vec![],
    kind: TaskNodeKind::Leaf,
    role: None,
    status: NodeStatus::Pending,
    output: None,
    compacted_output: None,
    error: None,
}];
let g = TaskGraph::new("Top goal".into(), HitlMode::None, nodes);
assert!(g.is_ok());

Source

pub fn validate_acyclic(&self) -> Result<(), TaskGraphError>

Validate that the dependency graph contains no cycles.

Uses DFS colouring (white → gray → black). Also validates that all depends_on ids resolve to existing nodes and that depth ≤ MAX_DEPTH.

§Errors

Returns the first structural violation found.

§Example — detecting a cycle

use std::collections::HashMap;
use gglib_core::domain::council::task_graph::{
    TaskGraph, TaskNode, TaskNodeKind, NodeId, NodeStatus, HitlMode, TaskGraphError,
};

let mut nodes = HashMap::new();
for (id, dep) in [("a", "b"), ("b", "a")] {
    nodes.insert(NodeId(id.into()), TaskNode {
        id: NodeId(id.into()),
        goal: id.into(),
        depends_on: vec![NodeId(dep.into())],
        tool_allowlist: vec![],
        kind: TaskNodeKind::Leaf,
        role: None,
        status: NodeStatus::Pending,
        output: None, compacted_output: None, error: None,
    });
}
let g = TaskGraph { goal: "cyclic".into(), hitl_mode: HitlMode::None, nodes };
assert!(matches!(g.validate_acyclic(), Err(TaskGraphError::Cycle(_))));

Source

pub fn validate_tool_allowlist( &self, catalog: &[ToolDefinition], ) -> Result<(), TaskGraphError>

Validate that every tool name in every node’s tool_allowlist exists in catalog.

Call this after TaskGraph::validate_acyclic when the runtime tool catalog is available.

§Example

use gglib_core::domain::council::task_graph::{
    TaskGraph, TaskNode, TaskNodeKind, NodeId, NodeStatus, HitlMode, TaskGraphError,
};
use gglib_core::ToolDefinition;

let catalog = vec![ToolDefinition {
    name: "web_search".into(),
    description: None,
    input_schema: None,
    title: None,
}];
let nodes = vec![TaskNode {
    id: NodeId("r".into()),
    goal: "research".into(),
    depends_on: vec![],
    tool_allowlist: vec!["nonexistent".into()],
    kind: TaskNodeKind::Leaf,
    role: None,
    status: NodeStatus::Pending,
    output: None, compacted_output: None, error: None,
}];
let g = TaskGraph::new("goal".into(), HitlMode::None, nodes).unwrap();
assert!(matches!(
    g.validate_tool_allowlist(&catalog),
    Err(TaskGraphError::UnknownTool { .. })
));

Source

pub fn roots(&self) -> Vec<&NodeId>

Return the ids of root nodes — those with an empty depends_on list.

§Example

use gglib_core::domain::council::task_graph::{
    TaskGraph, TaskNode, TaskNodeKind, NodeId, NodeStatus, HitlMode,
};

let nodes = vec![
    TaskNode { id: NodeId("root".into()), goal: "g".into(), depends_on: vec![],
               tool_allowlist: vec![], kind: TaskNodeKind::Leaf, role: None,
               status: NodeStatus::Pending,
               output: None, compacted_output: None, error: None },
    TaskNode { id: NodeId("child".into()), goal: "g".into(),
               depends_on: vec![NodeId("root".into())],
               tool_allowlist: vec![], kind: TaskNodeKind::Leaf, role: None,
               status: NodeStatus::Pending,
               output: None, compacted_output: None, error: None },
];
let g = TaskGraph::new("goal".into(), HitlMode::None, nodes).unwrap();
assert_eq!(g.roots().len(), 1);
assert_eq!(g.roots()[0], &NodeId("root".into()));

Source

pub fn ready_nodes(&self, completed: &HashSet<NodeId>) -> Vec<&NodeId>

Return the ids of nodes eligible to run given the set of already-completed nodes.

A node is eligible when:

It is not in completed.
All of its depends_on predecessors are in completed.

The returned slice is sorted by node id for deterministic ordering.

§Example

use std::collections::HashSet;
use gglib_core::domain::council::task_graph::{
    TaskGraph, TaskNode, TaskNodeKind, NodeId, NodeStatus, HitlMode,
};

let nodes = vec![
    TaskNode { id: NodeId("a".into()), goal: "g".into(), depends_on: vec![],
               tool_allowlist: vec![], kind: TaskNodeKind::Leaf, role: None,
               status: NodeStatus::Pending,
               output: None, compacted_output: None, error: None },
    TaskNode { id: NodeId("b".into()), goal: "g".into(),
               depends_on: vec![NodeId("a".into())],
               tool_allowlist: vec![], kind: TaskNodeKind::Leaf, role: None,
               status: NodeStatus::Pending,
               output: None, compacted_output: None, error: None },
];
let g = TaskGraph::new("goal".into(), HitlMode::None, nodes).unwrap();

// Nothing completed — only the root is ready.
let ready = g.ready_nodes(&HashSet::new());
assert_eq!(ready.len(), 1);
assert_eq!(ready[0], &NodeId("a".into()));

// "a" completed — "b" is now ready.
let done: HashSet<NodeId> = [NodeId("a".into())].into();
let ready = g.ready_nodes(&done);
assert_eq!(ready.len(), 1);
assert_eq!(ready[0], &NodeId("b".into()));

Source

pub fn total_node_count(&self) -> usize

Return the total number of nodes across all subgraphs combined.

Each TaskNodeKind::Leaf contributes 1. Each TaskNodeKind::Team contributes 1 (for itself) plus the recursive count of its subgraph.

This is the aggregate tally consulted by the warn-only token-cost estimator introduced in Phase J. Validation never fails on this value in Phase G; see MAX_TOTAL_NODES for the soft budget.

§Example

use gglib_core::domain::council::task_graph::{
    TaskGraph, TaskNode, TaskNodeKind, NodeId, NodeStatus, HitlMode,
};

let nodes = vec![
    TaskNode { id: NodeId("a".into()), goal: "g".into(), depends_on: vec![],
               tool_allowlist: vec![], kind: TaskNodeKind::Leaf, role: None,
               status: NodeStatus::Pending,
               output: None, compacted_output: None, error: None },
    TaskNode { id: NodeId("b".into()), goal: "g".into(),
               depends_on: vec![NodeId("a".into())],
               tool_allowlist: vec![], kind: TaskNodeKind::Leaf, role: None,
               status: NodeStatus::Pending,
               output: None, compacted_output: None, error: None },
];
let g = TaskGraph::new("goal".into(), HitlMode::None, nodes).unwrap();
assert_eq!(g.total_node_count(), 2);

Source

pub fn apply_diff(&mut self, diff: &GraphDiff) -> Result<(), TaskGraphError>

Apply a GraphDiff mutation in-place, then re-validate.

If either the mutation itself or the subsequent [validate_acyclic] call fails, the graph is restored to its pre-call state (clone-and-swap rollback) and the error is returned.

§Errors

Returns the first TaskGraphError encountered (pre-condition checks or post-mutation validation).

§Example

use gglib_core::domain::council::task_graph::{
    TaskGraph, TaskNode, TaskNodeKind, NodeId, NodeStatus, HitlMode,
    GraphDiff,
};

let nodes = vec![TaskNode {
    id: NodeId("a".into()), goal: "a".into(), depends_on: vec![],
    tool_allowlist: vec![], kind: TaskNodeKind::Leaf, role: None,
    status: NodeStatus::Pending, output: None,
    compacted_output: None, error: None,
}];
let mut g = TaskGraph::new("goal".into(), HitlMode::None, nodes).unwrap();

let new_node = TaskNode {
    id: NodeId("b".into()), goal: "b".into(),
    depends_on: vec![NodeId("a".into())],
    tool_allowlist: vec![], kind: TaskNodeKind::Leaf, role: None,
    status: NodeStatus::Pending, output: None,
    compacted_output: None, error: None,
};
g.apply_diff(&GraphDiff::AddNode { node: new_node }).unwrap();
assert_eq!(g.nodes.len(), 2);