Parallelism

Parallel nodes execute independent work concurrently. Concurrent execution can reduce elapsed time when no subflow or iteration requires the result of another.

A parallel node starts all work declared by the component. It does not select one subflow or iteration as a branch. The order in which that work completes is not deterministic.

Parallel Node Types

Component	Behavior
`ParallelFlowNode`	Executes multiple, different subflows concurrently.
`ParallelMapNode`	Executes the same subflow concurrently for the items in a collection.

Both components retain declared input and output contracts. Parallel execution does not change reference resolution, type compatibility, or reducer requirements.

ParallelFlowNode

A ParallelFlowNode represents multiple subflows that perform different, independent operations within an enclosing Flow. It executes every declared subflow concurrently rather than selecting one subflow as a branch.

When the ParallelFlowNode executes, it supplies its declared inputs to the subflows that consume them. Each subflow executes its own internal graph and returns its declared outputs. The ParallelFlowNode completes after the subflows complete and makes their results available through its output
contract. The order in which the subflows complete is not deterministic.

ParallelFlowNode Fields

Field	Requirement	Purpose
`component_type`	Required	Identifies the component as a `ParallelFlowNode`.
`id`	Required	Uniquely identifies the node for references and graph connections.
`name`	Required	Provides a human-readable component name.
`inputs`	Optional	Declares the typed values supplied to the subflows. Inputs with the same name can be shared when their types are compatible.
`outputs`	Optional	Declares the typed values returned from the subflows. Each output must have exactly one subflow as its provider.
`branches`	Optional	Declares named branches that outgoing control-flow edges can reference.
`subflows`	Optional	Defines or references the different Flows that execute concurrently.

The subflows must be independent: one subflow cannot consume another subflow's output or depend on its completion order.

ParallelMapNode

A ParallelMapNode represents repeated, concurrent execution of the same subflow for the items in a collection. It is appropriate when every collection item requires the same processing and no iteration depends on the result of another.

When the ParallelMapNode executes, it takes each item from its declared collection input and supplies that item to a separate execution of the
subflow. After the iterations complete, the configured reducers combine the subflow outputs into the node's declared outputs. Iterations can complete in any order; result construction follows the declared reducer behavior rather than incidental completion order.

ParallelMapNode Fields

Field	Requirement	Purpose
`component_type`	Required	Identifies the component as a `ParallelMapNode`.
`id`	Required	Uniquely identifies the node for references and graph connections.
`name`	Required	Provides a human-readable component name.
`inputs`	Optional	Declares the collections processed by the node. Each collection item specification must be compatible with the corresponding subflow input.
`outputs`	Optional	Declares the typed values produced after the subflow outputs are reduced.
`branches`	Optional	Declares named branches that outgoing control-flow edges can reference.
`subflow`	Required	Defines or references the Flow executed for each collection item.
`reducers`	Optional	Maps subflow output names to reduction operations. A subflow output without an explicit reducer uses `append`.

ParallelMapNode has the same collection, subflow, and reducer contracts as MapNode. The distinction is that ParallelMapNode permits the subflow iterations to execute concurrently.

ParallelFlowNode Example

An order-support Flow must retrieve shipment status, verify payment status, and determine return eligibility for the same order. These checks perform
different work, but each requires only order_id; none consumes the result of another check.

The three subflows have the following contracts:

Subflow	Input	Output
`shipment-check-flow`	`order_id` (`string`)	`shipment_status` (`string`)
`payment-check-flow`	`order_id` (`string`)	`payment_status` (`string`)
`return-eligibility-flow`	`order_id` (`string`)	`return_eligible` (`boolean`)

The enclosing Flow represents these independent checks as one ParallelFlowNode:

The ParallelFlowNode is defined as follows:

{
  "component_type": "ParallelFlowNode",
  "id": "run-order-checks",
  "name": "run_order_checks",
  "inputs": [
    {
      "title": "order_id",
      "type": "string"
    }
  ],
  "outputs": [
    {
      "title": "shipment_status",
      "type": "string"
    },
    {
      "title": "payment_status",
      "type": "string"
    },
    {
      "title": "return_eligible",
      "type": "boolean"
    }
  ],
  "branches": ["next"],
  "subflows": [
    {
      "$component_ref": "shipment-check-flow"
    },
    {
      "$component_ref": "payment-check-flow"
    },
    {
      "$component_ref": "return-eligibility-flow"
    }
  ]
}

The fields establish the boundary between the enclosing Flow and the three subflows:

inputs declares the order_id value shared by the subflows.
outputs declares the three values returned from the parallel work.
branches declares the next branch that can continue after the node completes.
subflows identifies the three Flows executed by the node.

Each output has exactly one provider:

ParallelFlowNode output	Providing subflow
`shipment_status`	`shipment-check-flow`
`payment_status`	`payment-check-flow`
`return_eligible`	`return-eligibility-flow`

During execution:

A data-flow edge transfers StartNode.order_id to ParallelFlowNode.order_id.
The runtime supplies order_id to each subflow.
The three subflows execute independently. Their completion order is not defined.
The runtime associates each returned value with the ParallelFlowNode output having the same name.
After the parallel work completes, data-flow edges transfer shipment_status, payment_status, and return_eligible to the nodes that consume them. The next branch identifies the possible control-flow continuation.

The three checks are represented by a ParallelFlowNode because they use different subflows and do not depend on one another. If one check required the result of another, those operations would instead require a sequential control-flow and data-flow relationship.

ParallelMapNode Example

An order-support Flow receives several order IDs and must perform the same status lookup for every order. The existing order-lookup-flow accepts one order_id and returns one order_status:

Direction	Name	Type
Input	`order_id`	`string`
Output	`order_status`	`string`

The ParallelMapNode executes a separate instance of this subflow for each order ID:

Description of the illustration ParallelMapNode Iteration and Reduction

The ParallelMapNode is defined as follows:

{
  "component_type": "ParallelMapNode",
  "id": "lookup-orders-concurrently",
  "name": "lookup_orders_concurrently",
  "inputs": [
    {
      "title": "iterated_order_id",
      "type": "array",
      "items": {
        "title": "order_id",
        "type": "string"
      }
    }
  ],
  "outputs": [
    {
      "title": "collected_order_status",
      "type": "array",
      "items": {
        "title": "order_status",
        "type": "string"
      }
    }
  ],
  "branches": ["next"],
  "subflow": {
    "$component_ref": "order-lookup-flow"
  },
  "reducers": {
    "order_status": "append"
  }
}

The fields establish the collection boundary:

inputs declares iterated_order_id, the array supplied by the enclosing Flow. Each array item matches the order_id input of the subflow.
outputs declares collected_order_status, the array produced after the iteration outputs are combined.
branches declares the next branch that can continue after the node completes.
subflow identifies the Flow executed for every order ID.
reducers applies append to the order_status value returned by each subflow execution.

During execution:

A data-flow edge transfers StartNode.order_ids to ParallelMapNode.iterated_order_id.
The runtime creates one subflow execution for each order ID and supplies that value as order-lookup-flow.order_id.
The subflow executions perform the same lookup independently and can complete in any order.
Each subflow execution returns one order_status.
The append reducer collects the statuses into ParallelMapNode.collected_order_status.
A data-flow edge transfers the collected array to EndNode.order_statuses. The next branch identifies the possible control-flow continuation after the node completes.

ParallelMapNode is appropriate because every collection item receives the same independent processing. A ParallelFlowNode, by contrast, is appropriate when the node executes several different subflows.