Flow
Command-composing atom. Yields nothing. Mutates nothing on its own. Exists to orchestrate Commands.
Properties
- Own effects: none.
- Children: at least one mutating atom (Command or Action, transitively); plus parameter Queries consumed internally.
- Yields: nothing.
Sub-shapes
| Sub-shape | Children | Examples |
|---|---|---|
| Strategy | mutating atoms (Command or Action) only | Sequential (>>), Parallel (|), Race (&), Gather, AnyN, Semaphore |
| Control | mutating atoms + Query params (cond, items, count) | IfDo(cond_q, body), ForEachDo(items_q, body), WhileDo(cond_q, body) |
Transparent wrappers (
Snapshot,Transaction,Retry,TryCatch) are not Flows. They wear hooks / policies around a body without composing Commands themselves. Covered in the next doc.
Forms
# Strategy
a >> b >> c # sequential
a | b # parallel
Race(c1, c2)
Gather(c1, c2)
# Control
IfDo(cond_q, then_cmd, else_cmd?)
ForEachDo(items_q, body_cmd)
WhileDo(cond_q, body_cmd)Examples
| Expression | Sub-shape | Effects |
|---|---|---|
Store1 >> Store2 | Strategy | WRITE |
Store1 | Store2 | Strategy | WRITE |
Race(Store1, Store2) | Strategy | WRITE |
Gather(Store1, Store2) | Strategy | WRITE |
IfDo(Eq(ref, 0), Store(ref, 1)) | Control | READ + WRITE |
ForEachDo(items_q, Print(item)) | Control | derived |
WhileDo(cond_q, Store(ref, v)) | Control | derived |
Composition
- Command / Action child. ✓ The point of Flow.
- Flow child. ✓ Composition stacks; observability preserved as long as leaves include mutating atoms.
- Query child as parameter. ✓ (cond, items, count) - Flow consumes the value internally as part of its orchestration logic.
- Query child as first-class peer. ✗ Flow doesn't return and doesn't mutate; an orphaned Query has no consumer (same observability failure as Command-in-Query).
Constraints
- Subtree must contain at least one mutating atom (Command or Action). Otherwise the whole composition is non-observable.
- Doesn't yield. No Stream Flow - same reason as no Stream Command.
- Doesn't mutate on its own. WRITE only ever appears via Command or Action descendants.
Why this kind
Real programs sequence Commands, dispatch them, repeat them, retry them. Putting that into Command would require Command-in-Command, breaking the atom-of-mutation purity. Flow keeps Commands as pure atoms and lifts orchestration into its own kind.