Flows
View SourceA Jido.Flow is the canonical authoring value for a local workflow. It lowers
to native Runic workflow data for execution through Jido.Exec.
See Flow Modules for the module API.
Canonical Value
A Flow has six fields:
| Field | Type | Purpose |
|---|---|---|
name | string | Stable human-readable name. |
description | string or nil | Optional description. |
schema | static Zoi schema or [] | Input contract. |
output_schema | static Zoi schema or [] | Output contract. |
components | ordered component list | Author-declared graph data. |
output | expression | Required Flow result. |
The component types are:
Jido.Flow.Stepfor one Action call;Jido.Flow.Subflowfor one child Flow module;Jido.Flow.Choicefor ordered routing with a required fallback;Jido.Flow.Mapfor ordered fan-out and fan-in;Jido.Flow.Reducefor a serial left fold; andJido.Flow.Iteratefor a bounded local loop; andJido.Flow.Dispatchfor one choice at the end of a Flow.
Each component has a name, explicit needs dependencies, and portable meta
data. Data references create inferred dependencies. Jido keeps explicit and
inferred dependencies separate.
A Flow can have at most one Dispatch component. Dispatch must be the last
component, and the Flow output must be the complete Dispatch result. Its
decision Action returns data for its expander Action. A normal expander result
completes the Flow. {:continue, input, target} ends the Flow and selects the
next executable for the same Jido.Exec.run/4 call.
Dispatch is not available through step-wise execution or as part of a Subflow. These limits keep continuation in one complete Exec call. See Dynamic Flows.
One Expression Grammar
Expressions contain portable scalar values, proper lists, maps, and
Jido.Flow.Ref values. Jido.Expr adds fixed Boolean, comparison, numeric,
and binary-concatenation operations. Flow fields accept these operations
directly or inside an optional expr(...) wrapper.
References can read Flow input, context, prior component results, and component-local Map, Reduce, or Iterate values. A reference is valid only in its defined scope.
Boolean references and literals are also valid conditions. Their evaluated values must be Boolean. See Expressions for the shared helper DSL, exact operations, runtime construction, errors, and limits.
The authoring grammar permits any expression at output. At execution, a
normal Flow result must be a map. Use Jido.Action.Output when a Flow must
return an intentional raw, stream, batch, or opaque value.
Three Authoring Forms
All supported forms produce the same canonical value:
- a module that uses
Jido.Flow; - Data definitions with
Jido.Flow.new/1, using component maps or constructors; and Jido.Flow.Codec.decode/2for stored JSON data.
The module DSL is the normal source-code API. Direct constructors are also an official API. Data definitions and Codec input pass through the same canonical validation.
Author Data And Runtime Data
A Flow stores author intent. Jido.Flow.compile/2 derives a
Jido.Flow.Compiled value with a native Runic.Workflow, component indexes,
source locations, and a compilation digest. Do not store the compiled value.
Jido.Exec compiles and runs a Flow. Step-wise execution exposes small
Jido.Exec.Work descriptions, including Join, input binding, fan-out, and
fan-in support work. Select a unit with its revision-scoped token. Use
Jido.Exec.native/1 for advanced, read-only native inspection.
Validation And Inspection
{:ok, flow} = Jido.Flow.validate(flow)
{:ok, flow} = Jido.Flow.validate_executable(flow)
{:ok, dependencies} = Jido.Flow.dependencies(flow)
{:ok, explanation} = Jido.Flow.explain(flow)
{:ok, identity} = Jido.Flow.semantic_identity(flow)validate/1 is inert and does not load or check target modules.
validate_executable/1 also checks Action and child Flow contracts. Neither
function runs Action work.
All authoring forms use the same graph rules. DSL errors identify the source
declaration; new/1 and validate/1 return the first error.
Continue with Flow DSL, Flow Data Definitions, and Store Flows As JSON.
Deferred Effect Requests
Return {:ok, output, requests} from an Action to
request effects after success. Flow collects these opaque requests in canonical
dependency order and returns the complete batch with its final output. Exec
does not execute effects. Failed execution returns no executable batch.
The optional third success element must be a proper list of effect requests.
See Execution for ordering, collections, continuations, and migration.