Struct BranchBuilder 

pub struct BranchBuilder { /* private fields */ }

Accumulates the arms of an in-construction Op::Branch (phi/merge) node before finalize_branches validates them and emits the node. Created by Graph::open_branch.

The multi-path structure is an arena fact, not an overlay: a Branch node’s divergent arms are its inputs (each input is one route’s exit), and the op carries an explicit reconverge_at. The builder is a pure NodeId accumulator — it holds no graph reference — so the graph remains free to keep appending nodes (further arms) while the builder is open. Nothing mutates the arena until finalize_branches, which is the single validation gate.

Implementations

impl BranchBuilder

pub fn add_arm(&mut self, exit: NodeId) -> &mut Self

Append one arm by its exit node — the node whose value the merge reads for this route. The first arm added is arm 0, the runnability fallback: reconverge_at must read arm 0’s exit so a finalized-but-not-yet-route-picked graph still realizes (validated in finalize_branches).

Returns &mut Self for chaining. Validation is deferred to finalize — add_arm never inspects the graph and never fails.

pub fn diverge(&self) -> NodeId

The shared diverge point this branch departs from.

pub fn arms(&self) -> &[NodeId]

The arm exits accumulated so far, in add order (arm 0 first).

pub fn finalize_branches( self, graph: &mut Graph, reconverge_at: NodeId, ) -> Result<Option<NodeId>, Error>

Validate and emit the Op::Branch node, returning its fresh NodeId. This is the single build-time gate; it never panics, surfacing every rejection as fuel_ir::error::Error::InvalidBranch.

Returns:

• Ok(Some(branch_id)) — a multi-arm branch was emitted.
• Ok(None) — a single-arm branch collapsed to that arm (no real decision point), leaving the arena untouched.
• Err(Error::InvalidBranch { .. }) — a validation rule failed.

Validation rules (all checked before any mutation):

1. At least one arm; diverge, reconverge_at, and every arm exit are in-bounds.
2. Descendant reconverge_at — the merge must be a forward descendant of (and distinct from) diverge.
3. Internally-disjoint arms — each arm’s interior nodes (the nodes on paths diverge → exit, excluding the shared diverge) must neither be shared with another arm nor read by any node outside the branch (reconverge_at reading an arm exit is the one allowed external consumer).
4. Cast-to-uniform — all arm exits agree on shape & dtype. PR-A1 validates uniformity and errors on mismatch (it does not insert Cast nodes); dtype-lowered alternatives must therefore cast back to the merge dtype inside their arm before the exit.
5. Arm-0 runnability — reconverge_at must read arm 0’s exit, so a finalized-but-unpicked graph still realizes on arm 0.

Trait Implementations

impl Clone for BranchBuilder

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BranchBuilder

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

Formats the value using the given formatter.