Flow

A Flow is a directed acyclic graph (DAG) of nodes that defines the execution logic of a Tool. Each node performs a specific operation, and edges define the data flow and execution order between nodes. Flows are designed visually in Flow Studio and stored as part of the Tool spec.

Flow Graph Structure

Every Flow consists of three parts:

• Nodes -- Individual operations (read data, write data, transform, branch, call external service, etc.)
• Edges -- Connections between nodes that define execution order and data passing
• Start Node -- The entry point of the flow. Exactly one start node is required.

Node Types

Nodes are organized into four categories:

Category	Node	Description
Data	Read	Fetch records from an Entity or Composite
Data	Write	Create, update, transition status, or soft-delete an Entity record
Logic	Transform	Data transformation using the Value DSL
Logic	If/Switch	Conditional branching based on Value DSL expressions
Logic	Retry	Retry a downstream node on failure with configurable count and backoff
Logic	Timeout	Set an execution time limit on a downstream node
External	Payment	Call a payment service (Stripe, etc.)
External	Email/SMS	Send an email or SMS notification
External	HTTP Request	Call an external HTTP API
Safety	Transaction	Mark explicit transaction boundaries (begin/commit/rollback)
Safety	Policy Check	Run a Policy check (row limits, budget constraints)
Safety	Assert	Enforce an invariant -- if the expression is false, the flow aborts

Data Nodes

Read nodes query an Entity or Composite with optional filters, sorting, and pagination. Every Read node must specify a limit to prevent unbounded queries.

Write nodes modify Entity records. Supported actions are create, update, transition (change status), and softDelete. All Write nodes must be placed inside a Transaction boundary.

Logic Nodes

Transform nodes compute derived values using Value DSL expressions. They take input data and produce new values without side effects.

If nodes evaluate a boolean Value DSL expression and branch to one of two paths (then or else). Switch nodes evaluate an expression and branch to one of multiple named paths.

Retry nodes wrap a downstream operation with retry logic, specifying maximum attempts and backoff strategy (fixed or exponential).

Timeout nodes set a maximum execution duration for a downstream operation.

External Nodes

External nodes call services outside the Fascia executor. They should always have Retry and Timeout nodes configured. External nodes with side effects must not be placed inside a Transaction boundary -- if the transaction rolls back, the external side effect cannot be undone.

Safety Nodes

Transaction nodes mark the start and end of a database transaction. All Write nodes must be enclosed within Transaction boundaries.

Policy Check nodes evaluate a Policy at runtime. If the policy condition fails, the flow is aborted based on the policy action (block, warn, or escalate).

Assert nodes evaluate a Value DSL boolean expression. If the assertion fails, the flow aborts with the specified error message. Assertions are used to enforce invariants and preconditions.

Edges and Data Mapping

Edges connect nodes in execution order. Each edge can optionally define a data mapping that transforms the output of the source node into the expected input of the target node. Data mappings use Value DSL expressions.

When a node has multiple incoming edges (such as after an If/Switch convergence), the data from all paths is merged according to the mapping rules.

Validation Rules

Every Flow must satisfy these structural rules before it can be deployed:

1. Acyclic -- The graph must be a DAG. Cycles are not allowed. This is validated using topological sorting (Kahn's algorithm).
2. Single start node -- Exactly one node is designated as the entry point.
3. All paths terminate -- Every path through the graph must reach a terminal node (a node with no outgoing edges).
4. Writes inside transactions -- All Write nodes must be enclosed within Transaction begin/commit boundaries.
5. External nodes outside transactions -- External nodes with side effects should not be placed inside Transaction boundaries to prevent irrecoverable states.
6. External nodes have retry -- External nodes (Payment, Email/SMS, HTTP Request) should have Retry configuration to handle transient failures.
7. External nodes have timeout -- External nodes should have a Timeout to prevent indefinite blocking.

Violations of rules 1-4 result in a Red risk level and block deployment. Violations of rules 5-7 result in a Yellow risk level that requires acknowledgment. See Policy for more on risk classification.