Wait Node

What Wait is and why it exists

Wait is the synchronization node in NodeFox. It exists so parallel or dependent branches can converge only when optional conditions are satisfied. Without Wait, workflows often merge prematurely, causing partial context, duplicate writes, or inconsistent branch outcomes.

Wait is especially valuable in fan-out/fan-in designs where independent branches must complete before a final decision or side effect is allowed.

Execution behavior

Wait evaluates configured conditions, usually against values set through Global. It remains blocked until all optional conditions pass. Once released, execution continues deterministically to downstream nodes.

Because Wait behavior is explicit, teams can inspect stalled runs and identify which condition prevented progression.

Configuration details

Wait currently uses a condition-based variant.

Field	What it controls	Practical guidance
`Conditions`	List of optional checks	Keep condition sets concise and aligned with branch ownership.
`Evaluator`	Comparison logic (`equals`, `contains`, `greater than`, etc.)	Use deterministic evaluators and avoid ambiguous string checks for critical controls.
`Value`	Expected comparison target (supports slot refs)	Keep expected values normalized upstream to reduce false mismatches.
Source variable	Global variable each condition reads	Use explicit namespaced keys and clear producer ownership.

All conditions must pass for release. Design condition sets so they reflect real completion criteria, not assumptions.

Condition row structure

Each condition row is:

Variable Name + Evaluator + Value

Variable Name: global key to read (branch_a_done, approval_state, etc.)
Evaluator: comparison operator
Value: expected target value (literal or slot reference)

Evaluator reference

Wait condition checks commonly use:

Evaluator	Typical use
`==` / `equals`	exact readiness checks
`!=` / `not equals`	explicit mismatch checks
`>` / `greater than`	numeric progress or threshold checks
`<` / `less than`	numeric lower-bound checks
`>=` / `greater than or equal`	inclusive threshold checks
`<=` / `less than or equal`	inclusive upper-bound checks
`contains`	token/list membership checks
`not contains`	exclusion checks
`starts with`	prefix-based state checks
`ends with`	suffix-based state checks
`regex match`	pattern-based readiness checks

Use deterministic, normalized values for Wait conditions (true vs "true", numeric vs string) so release logic remains predictable and easy to diagnose.

Production usage patterns

A common pattern is Parallel branches -> Global(Set completion flags) -> Wait -> merge Decision. In this pattern, each branch writes explicit completion state and Wait acts as the convergence gate.

Another pattern is coordinating external dependency readiness. For example, one branch triggers an external process while another branch polls status; Wait releases only when readiness state and policy conditions are both satisfied.

You can also use Wait as a temporal safety valve by combining readiness conditions with bounded retry paths in upstream branches so release only occurs when both data and control state are valid.

Design checklist for reliable Wait nodes

Define who sets each condition variable.
Define timeout or escalation behavior outside Wait.
Ensure condition values are normalized (true vs "true", numeric types, etc.).
Route timeout/failure to explicit fallback branches.
Log condition snapshots for stalled-run diagnosis.

Common mistakes to avoid

The most common mistake is waiting on variables that are never set in all branches. This creates indefinite stalls that look like runtime failures but are actually design gaps. Another issue is using loosely named flags that collide across unrelated branches.

Treat Wait conditions as formal contracts. If a condition is optional for release, that condition should have a clearly owned producer branch.

What to monitor

average wait duration by workflow
timeout/escalation frequency
condition mismatch distribution by evaluator type
stalled runs grouped by missing producer branch