Flows

A Flow plans and tracks one execution toward its Goal Steps.

Goals and Planning

A Flow is one execution toward a set of Goal Steps. Its initial values seed the state, and the Goals tell Argyll which outcomes to produce. Argyll follows the registered Attribute dependencies backward from those Goals to build an Execution Plan: the Steps and dependencies selected for that run.

Flow Execution

When a Flow starts, Argyll compiles its Execution Plan and identifies the Steps whose inputs are already available. Those Steps run in parallel within their configured limits. Each committed result may satisfy another Step’s inputs, so execution advances through the dependency graph until every Goal completes or a Goal becomes unreachable.

Flow Lifecycle

A Flow moves through three phases:

graph TD Active["Active\n(steps executing)"] Terminal["Terminal\n(completed or failed)"] Deactivated["Deactivated\n(no remaining side effects)"] Active -->|"all goals satisfied"| Terminal Active -->|"Goal Step failed"| Terminal Terminal -->|"all work settled,\nrollback boundary closed"| Deactivated

Active: Steps are running, events are being recorded, the Flow is progressing toward its Goals.

Terminal (completed or failed): The outcome is decided and available to callers. Either every Goal succeeded or at least one Goal failed. Work that was already active continues to report its result, and compensation can continue after failure, preserving the complete execution history.

Deactivated: The Flow is terminal, all active and compensating work has settled, and its parent has released it. Deactivation marks the end of the Flow’s side-effect history.

A Sub-Flow reports its result as soon as its own work finishes. It remains terminal but active until its parent releases it, preserving the parent’s ability to request rollback. Once the root Flow settles, that release propagates through its children and each Flow deactivates.

sequenceDiagram participant Parent participant Child Child->>Child: Own work finished Child->>Parent: Result Note over Child: Terminal, not deactivated Parent->>Parent: Continues, may still fail Parent->>Parent: Deactivates Parent->>Child: Release Note over Child: Deactivated

The full Flow state and terminal events report completed or failed as soon as the outcome commits. The lightweight status and query indexes continue to report active until deactivation, then publish the final status after all remaining work has settled.

Flow State

Every Flow has explicit state that you can inspect at any time:

What Steps have executed and what status they reached
What outputs each Step produced
What Steps are still pending
Why the Flow is in its current state

Reusable Flows

A Flow Step packages a reusable set of Goals behind the Step contract. Its inputs initialize the child Flow, and its mapped outputs return child results to the parent Flow.

A Flow Step may name a Space to restrict planning for its child Flow. Every configured Goal must belong to that Space. While the Flow Step holds that reference, Argyll rejects deletion of the Space or Goal and rejects selector or label changes that would remove a Goal from the Space.