Struct HierarchyTracker 

pub struct HierarchyTracker { /* private fields */ }

Tracks parent-child task relationships and enforces lifecycle coupling.

The tracker is not persisted directly. At bootstrap it is reconstructed from the parent_task_id field present on each TaskSpec in the WAL, then terminal status is inferred from run states in the projection.

The dispatch loop calls mark_terminal whenever a task’s runs all reach terminal state, keeping orphan prevention accurate throughout the engine lifetime.

Implementations

impl HierarchyTracker

pub fn new() -> Self

Creates a new tracker with the default maximum depth (8).

pub fn with_max_depth(max_depth: usize) -> Self

Creates a new tracker with the given maximum nesting depth.

A root task is at depth 0. A direct child is at depth 1. max_depth = 8 allows up to depth 8 (nine levels total).

pub fn register_child( &mut self, parent: TaskId, child: TaskId, ) -> Result<(), HierarchyError>

Registers a parent-child relationship.

Errors

• HierarchyError::OrphanPrevention if the parent is already terminal.
• HierarchyError::DepthLimitExceeded if adding this child would exceed the configured maximum nesting depth.

pub fn children_of(&self, parent: TaskId) -> impl Iterator<Item = TaskId> + '_

Returns an iterator over the direct children of parent.

pub fn parent_of(&self, child: TaskId) -> Option<TaskId>

Returns the parent of child, if any.

pub fn has_children(&self, task_id: TaskId) -> bool

Returns true if task_id has any registered children.

pub fn is_terminal(&self, task_id: TaskId) -> bool

Returns true if task_id has been marked terminal.

pub fn mark_terminal(&mut self, task_id: TaskId)

Marks task_id as having reached a terminal state.

Called by the dispatch loop when all runs for a task become terminal. Once marked terminal, the task cannot accept new children.

pub fn depth(&self, task_id: TaskId) -> usize

Returns the nesting depth of task_id (0 = root, no parent).

Walks up the parent chain; O(depth) time. With max_depth capped at 8, this is effectively constant-time and caching is unnecessary.

pub fn gc_subtree(&mut self, task_id: TaskId)

Removes all tracker state for a fully-terminal task and its descendants.

Safety constraint: Only call when task_id AND all its descendants are terminal (i.e., collect_cancellation_cascade(task_id) returns empty). Violating this precondition can remove entries still needed for cascade protection or orphan prevention of in-flight tasks.

Called by the dispatch loop after the hierarchy cascade for task_id is fully quenched (all descendants terminal).

pub fn collect_cancellation_cascade(&self, task_id: TaskId) -> Vec<TaskId>

Collects all non-terminal descendants of task_id for cascading cancellation.

Traverses the subtree in breadth-first order (BFS) starting from task_id’s direct children. Results are returned in BFS visitation order. Descendants already marked terminal (via mark_terminal) are excluded from the result, as they require no further action.

Returns an empty Vec when task_id has no children or all descendants are already terminal (self-quenching: repeated calls are safe and cheap).

Trait Implementations

impl Clone for HierarchyTracker

fn clone(&self) -> HierarchyTracker

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HierarchyTracker

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for HierarchyTracker

fn default() -> HierarchyTracker

Returns the “default value” for a type.

impl PartialEq for HierarchyTracker

fn eq(&self, other: &HierarchyTracker) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for HierarchyTracker

impl StructuralPartialEq for HierarchyTracker