Loop `loop`

A loop container checks a deterministic condition before each execution of its child-canvas scope. Use it for pagination, bounded polling, or repeated processing with a clear exit rule. Do not read unrecorded external state directly from the condition. A child task should first obtain the latest external value and commit it to history so the next condition evaluation can replay from durable data.

Condition and safety bound

When condition evaluates to true, the runtime enters another iteration. When it is false, control leaves through done. max_iterations is the host safety limit and accepts values from 1 through 10000. Decide what reaching that limit means for the business flow, such as entering a failure, timeout, or manual-review path. The limit protects runtime capacity, but it does not replace a meaningful exit condition or justify an arbitrarily high value.

start_node_id must point to the container's single internal loop-start. Every child uses the container ID as parentId, and the entry node's next port connects to the first executable child. Child edges cannot cross the container boundary. The loop behavior belongs to the container, while the surrounding DAG remains acyclic.

Recovery and capacity checks

Persist every value needed by the next condition, including the iteration number, page cursor, accumulated status, or last observed result. Do not depend on process memory. Test an initially false condition, exit after one pass, the maximum-iteration path, task failure, process restart, and long history behavior. If the loop can run for many iterations, place a continuation node at a stable boundary and pass only the cursor and compact state needed by the next segment. Define polling intervals and backoff in actual task or wait nodes so replay never depends on wall-clock guesses hidden in the condition.

Use it for a loop child canvas with a condition and a hard iteration cap. The condition is checked before entering the nested scope each time.

Runtime behavior

The container emits no runtime command on its own. The host compiles each pass into durable decisions and continues through done when the condition is false or the cap is reached.

Node contract

Type: loop
Role: Child-canvas container
Runtime binding: Host compilation
Durable identity: Defined by graph structure

Configuration properties

Property	Type and control	Default	Rules
`condition`Continue condition	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"lt","left":{"op":"field","path":"loop.index"},"right":{"op":"literal","value":10}}}`	Condition checked before the next loop scope execution.Required
`max_iterations`Maximum iterations	`int`IntInput	`100`	Host safety bound for loop compilation.Required · Advanced · Range 1 to 10000 / 1
`start_node_id`Start node ID	`str`StrInput	`loop-start`	Stable identity of the loop-start child in this container scope.Required · Advanced

Child-canvas structure

Property	Type and control	Rules
`loop-start`	`internal node`	The single nested entry whose parentId points to loopRequired
`parentId`	`node id`	Every nested node uses the same container IDRequired

Ports

Direction	Port ID	Kind	Value types
Input	`in`In	control	`FlowControl`
Output	`done`Done	control	`FlowControl`

Node JSON example

The CLI creates the same structure from manifest defaults. Canvas position, title, and selection are presentation data.

workflow.json

{
  "position": {
    "x": 320,
    "y": 160
  },
  "id": "example-loop",
  "data": {
    "condition": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "lt",
        "left": {
          "op": "field",
          "path": "loop.index"
        },
        "right": {
          "op": "literal",
          "value": 10
        }
      }
    },
    "max_iterations": 100,
    "start_node_id": "loop-start",
    "type": "loop"
  }
}

CLI usage

Inspect the installed manifest first, then create the node and validate the complete workflow. Every command emits JSON.

Terminal

a3s-flow node loop --pretty
a3s-flow new loop --id example-loop --pretty
a3s-flow validate workflow.json --pretty
a3s-flow compile workflow.json --pretty
a3s-flow digest workflow.json --pretty

Skill usage

The package includes the a3s-flow Skill. It queries the CLI catalog before creating, validating, compiling, and digesting a workflow.

Prompt

Use $a3s-flow to add the "loop" node to workflow.json, connect valid ports, and validate the result.

CLI usage · Skill usage

Operational notes

start_node_id must point to the nested loop-start.
Use max_iterations to bound a loop that cannot exit.
Express repetition with the container, never a back edge.

#Loop loop

#Condition and safety bound

#Recovery and capacity checks