Struct BranchStateMachine 

pub struct BranchStateMachine { /* private fields */ }

Branch State Machine for trajectory DAGs.

Provides high-level operations for managing branches, including:

• split: Create a new branch from a subtree (DLM port)
• merge: Combine branches back together
• traverse: Navigate between branches
• recover: Find and reactivate “lost” branches

Design (from DLM)

The state machine maintains:

• A mapping of branch IDs to Branch structs
• The currently active branch
• A history of all branch operations
• Fork points where branching occurred

Example

let graph = TrajectoryGraph::from_edges(edges);
let mut machine = BranchStateMachine::from_graph(graph);

// Split at a fork point
let result = machine.split(fork_node_id)?;
println!("Created new branch: {}", result.new_branch);

// Traverse to the new branch
machine.traverse(result.new_branch)?;

// Later, merge back
machine.merge(result.new_branch, result.original_branch)?;

Implementations

impl BranchStateMachine

pub fn from_graph(graph: TrajectoryGraph) -> Self

Create a new state machine from a trajectory graph.

Analyzes the graph to identify branch points and creates the initial branch structure.

pub fn split(&mut self, node_id: NodeId) -> Result<SplitResult, BranchError>

Split a branch at a given node, creating a new independent branch.

This is the core operation for solving the “lost branch” problem, ported from DLM’s StateMachine.split().

Arguments

• node_id - The node at which to split

Returns

• SplitResult containing the original and new branch IDs

Errors

• NodeNotFound if the node doesn’t exist
• CannotSplitRoot if trying to split at the root

Example

let result = machine.split(fork_node_id)?;
// The new branch is now independent and can be explored separately
machine.traverse(result.new_branch)?;

pub fn merge( &mut self, from_branch: BranchId, into_branch: BranchId, ) -> Result<MergeResult, BranchError>

Merge a branch into another branch.

Ported from DLM’s StateMachine.merge().

Arguments

• from_branch - The branch to merge (will become inactive)
• into_branch - The branch to receive the merge

Returns

• MergeResult with merge details

pub fn traverse(&mut self, target_branch: BranchId) -> Result<(), BranchError>

Traverse from current branch to another branch.

Changes the active branch context.

pub fn archive( &mut self, branch_id: BranchId, reason: Option<String>, ) -> Result<(), BranchError>

Archive a branch (preserve but mark inactive).

pub fn current(&self) -> Option<&Branch>

Get the current branch.

pub fn get_branch(&self, branch_id: BranchId) -> Option<&Branch>

Get a branch by ID.

pub fn active_branches(&self) -> impl Iterator<Item = &Branch>

Get all active branches.

pub fn all_branches(&self) -> impl Iterator<Item = &Branch>

Get all branches (including inactive).

pub fn branch_count(&self) -> usize

Get the number of branches.

pub fn fork_points(&self) -> impl Iterator<Item = &ForkPoint>

Get all fork points.

pub fn history(&self) -> &[BranchOperation]

Get the operation history.

pub fn context(&self) -> &BranchContext

Get the current context.

pub fn find_branch_for_node(&self, node_id: NodeId) -> Option<BranchId>

Find which branch contains a node.

pub fn child_branches(&self, branch_id: BranchId) -> Vec<BranchId>

Get child branches of a given branch.

pub fn graph(&self) -> &TrajectoryGraph

Get reference to the underlying graph.

Trait Implementations

impl Clone for BranchStateMachine

fn clone(&self) -> BranchStateMachine

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BranchStateMachine

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

Formats the value using the given formatter.