Implicit State Derivation v2 Proposal
Status: 🟡 DRAFT
Supersedes: IMPLICIT_STATES_PROPOSAL.md (REJECTED)
Executive Summary
This proposal demonstrates that implicit state derivation is fully achievable in EventFlow. The v1 proposal rejection was overly pessimistic - structural analysis of code can determine states with high confidence in virtually all cases.
Key Insight
The v1 rejection's "calculator ambiguity" example is NOT ambiguous:
flow
on :add (api) // No guards = can run anytime
on :subtract (api) // No guards = can run anytimeWithout guards, these handlers ARE independent. The code tells us this - there's no ambiguity to resolve. No guards + No emit = Single state machine.
Three Derivation Strategies
- Event-Flow Derivation (95% confidence) - From
emit ... to @actor+ response handlers - Guard-Derived States (85% confidence) - From
? $variable existsand similar guards - Context-Derived States (80% confidence) - From mode variables with enumerated values
What's Actually Undecidable?
Very little. The only truly undecidable cases are:
- Timeout events without explicit source or scheduling
- Race conditions in parallel responses (runtime concern, not derivation)
Machine mode markers are OPTIONAL - they document intent but don't change derivation. The algorithm derives states from code structure, not developer annotations.
Addressing the v1 Rejection
The Original Rejection Reason
The relationship between event handlers (whether they form a sequential process or are independent operations) is semantic information that cannot be inferred from code structure alone.
Example: Given two handlers
:checkoutand:payment_received, the CLI cannot determine if these are part of a sequential checkout process, or two independent operations (like a calculator with separate:add,:subtractoperations).
Why This Rejection is Overly Pessimistic
The rejection treats all event handlers as equally ambiguous. In reality, structural and contextual signals exist that disambiguate most cases:
| Signal | What It Tells Us | Confidence |
|---|---|---|
emit :X to @Y + on :response from @Y | Sequential request/response | High |
(api) marker on handler | External entry point | High |
from @actor clause | Event origin is explicit | High |
Guards checking $variable exists | Handler depends on prior state | Medium |
| Context variable data flow | Handler depends on prior handler | Medium |
scenario: block grouping | Events are related | Medium |
The :checkout → :payment_received example is not ambiguous when we look at the full context:
flow
on :checkout from @customer (api)
emit :request_payment to @payment // ← This TELLS us we're waiting for payment
on :payment_received from @payment // ← This is the RESPONSEThe emit ... to @payment followed by on ... from @payment is an explicit request/response pattern. This is not semantic guessing - it's structural analysis.
What About the Calculator Example?
The v1 rejection used a calculator as an example of ambiguity:
flow
machine: @calculator
on :add (api)
$result increases by $value
on :subtract (api)
$result decreases by $valueThis is NOT ambiguous. Here's why:
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ FUNDAMENTAL RULE: No Guards = No Sequence = Independent Operations │
│ │
│ If handler B required handler A to run first, there would be a guard: │
│ │
│ on :subtract (api) │
│ ? $add_was_called ← This guard would ENFORCE sequence │
│ $result decreases by $value │
│ │
│ Without such a guard, BOTH handlers can run at ANY time. │
│ This means they ARE independent - not "might be" independent. │
│ │
│ RESULT: Single state (#ready) with self-loops │
│ │
└─────────────────────────────────────────────────────────────────────────┘The derivation is deterministic:
| Code Structure | Derivation Result |
|---|---|
Multiple (api) handlers, no guards | Single #ready state, all handlers loop back |
Multiple (api) handlers, with guards | Guards define the implicit states |
Handlers with emit/from patterns | Wait states from communication patterns |
EventFlow derives states from CODE, not developer intent. If a developer wants sequential behavior but doesn't write guards, that's either:
- A bug (guards should be added)
- Or they actually don't need sequencing
The Core Derivation Principle
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ THE STATE DERIVATION AXIOM │
│ │
│ A STATE exists when and only when: │
│ │
│ 1. A WAIT POINT exists (machine is waiting for an event) │
│ - After emit to another actor │
│ - After queued/async operation │
│ - At machine start (initial state) │
│ │
│ 2. A GUARD PARTITION exists (behavior differs based on condition) │
│ - ? $variable exists │
│ - ? $mode is "value" │
│ - ? machine is in #state │
│ │
│ 3. An EXPLICIT DECLARATION exists │
│ - moves to #state │
│ - machine mode marker │
│ │
│ If NONE of these exist → Single state with self-loops │
│ │
└─────────────────────────────────────────────────────────────────────────┘Core Insight: State Types by Derivation Source
States in EventFlow can be categorized by how they are derived:
┌─────────────────────────────────────────────────────────────────────────────┐
│ STATE DERIVATION TAXONOMY │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 1. EVENT-FLOW DERIVED STATES │ │
│ │ Source: emit/response patterns, cross-machine communication │ │
│ │ Confidence: HIGH │ │
│ │ Example: emit :pay to @payment → waiting → on :paid from @pay │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 2. GUARD-DERIVED STATES │ │
│ │ Source: Conditional logic that partitions behavior │ │
│ │ Confidence: MEDIUM │ │
│ │ Example: ? $pending_op exists → "has pending operation" state │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 3. CONTEXT-DERIVED STATES │ │
│ │ Source: Variable existence/value creating behavior modes │ │
│ │ Confidence: MEDIUM │ │
│ │ Example: $mode = "degrees" vs "radians" → different calc modes │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 4. DECLARED STATES (Explicit) │ │
│ │ Source: Developer uses `moves to #state` or mode markers │ │
│ │ Confidence: EXPLICIT │ │
│ │ Example: order moves to #shipped │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 5. DEFAULT STATE (Stateless Operations) │ │
│ │ Source: No state transitions, all handlers return to #ready │ │
│ │ Confidence: HIGH (when declared with mode marker) │ │
│ │ Example: machine: @calculator (stateless) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Algorithm 1: Event-Flow Derivation
Overview
Event-flow derivation identifies states from explicit communication patterns between machines or actors. This is the highest-confidence derivation method.
Algorithm
ALGORITHM: EventFlowStateDerivation
INPUT:
- flow_file: Parsed EventFlow AST
OUTPUT:
- states: List of derived states with transitions
PROCEDURE:
1. IDENTIFY ENTRY POINTS
─────────────────────
For each handler H in flow_file:
If H has (api) marker:
Add H.event to entry_points
Mark as "can be triggered from #initial"
2. BUILD EMIT/RESPONSE GRAPH
──────────────────────────
For each handler H in flow_file:
For each emit E in H.actions:
Create edge: H.event → E.target_event
If E has "to @actor" clause:
expected_responses = FindHandlers(from: @actor)
For each R in expected_responses:
Create edge: E → R (response relationship)
Mark transition: "after E, waiting for R"
3. IDENTIFY WAIT POINTS
─────────────────────
For each emit E with expected_responses:
Create state: #after_{E.event} or #awaiting_{response.event}
Type: waiting
Waiting_for: expected_responses
4. IDENTIFY TERMINAL POINTS
─────────────────────────
For each handler H:
If H has no outgoing edges (no emit, no further handlers expected):
Create state: #after_{H.event}
Type: terminal
Analyze for outcome (success/failure/neutral)
5. CONNECT TRANSITIONS
────────────────────
For each state S:
incoming = events that lead to S
outgoing = events that exit S
Create transition map
RETURN states with full transition graphVisual Representation
EMIT/RESPONSE PATTERN DETECTION
┌─────────────────────────────────────────────────────────────────┐
│ │
│ on :checkout from @customer (api) │
│ validate cart │
│ emit :request_payment to @payment ──────────┐ │
│ │ │ │
│ │ │ │
│ ▼ │ │
│ ╔═════════════════════╗ │ │
│ ║ WAIT POINT ║ │ │
│ ║ #awaiting_payment ║ │ │
│ ║ ║ │ │
│ ║ waiting_for: ║ │ │
│ ║ - :payment_success║◄─────────────────┤ │
│ ║ - :payment_failed ║◄─────────────────┤ │
│ ╚══════════╤══════════╝ │ │
│ │ │ │
│ ┌───────────────┴────────────────┐ │ │
│ ▼ ▼ │ │
│ on :payment_success on :payment_failed │ │
│ from @payment from @payment │ │
│ │ │ │ │
│ ▼ ▼ │ │
│ ┌──────────┐ ┌──────────┐ │ │
│ │ TERMINAL │ │ TERMINAL │ │ │
│ │#confirmed│ │ #failed │ │ │
│ │ success │ │ failure │ │ │
│ └──────────┘ └──────────┘ │ │
│ │
│ DERIVED BECAUSE: emit to @payment creates expectation │
│ for response from @payment │
└─────────────────────────────────────────────────────────────────┘Pattern Catalog
| Pattern | Detection | Wait State Created |
|---|---|---|
emit :X to @Y | Direct emit to actor | #awaiting_{X}_response |
emit async :X + handler exists | Async with callback | #processing_{X} |
(queued api) | Background processing | #queued_{event} |
reply 202 async for | Deferred response | #processing_{request} |
emit :X + on :X_success / on :X_failed | Success/failure pattern | #awaiting_{X}_result |
Algorithm 2: Guard-Derived States
Overview
Guard-derived states emerge when conditional logic partitions the machine's behavior based on runtime conditions. Guards that check for the existence or value of context variables effectively define implicit states.
Core Insight
flow
on :number (api)
? $pending_operation exists // ← This guard IMPLIES a state
perform calculation
otherwise
$operand becomes $value // ← Different behavior = different stateThe guard ? $pending_operation exists tells us:
- There's a state where
$pending_operationdoes NOT exist - There's a state where
$pending_operationDOES exist - These states have different behaviors for the same event
Algorithm
ALGORITHM: GuardDerivedStateDetection
INPUT:
- flow_file: Parsed EventFlow AST
OUTPUT:
- implicit_states: States derived from guard conditions
- state_constraints: What context conditions define each state
PROCEDURE:
1. EXTRACT GUARD CONDITIONS
─────────────────────────
guard_conditions = {}
For each handler H in flow_file:
For each guard G in H.guards:
condition = ParseCondition(G)
guard_conditions[H.event].add(condition)
2. IDENTIFY STATE-DEFINING GUARDS
───────────────────────────────
State-defining guards are those that:
a) Check for variable EXISTENCE: "$X exists", "$X is empty"
b) Check for specific VALUES: "$mode is 'degrees'"
c) Check for STATE-LIKE values: "$status is 'pending'"
For each condition C in guard_conditions:
If C matches existence pattern:
Create state pair:
- #has_{variable}
- #no_{variable} (or #awaiting_{variable})
If C matches value pattern:
Create state: #{variable}_{value}
If C matches state-like pattern:
Create state: #{value}
3. BUILD STATE CONSTRAINT MAP
───────────────────────────
For each handler H:
active_states = []
For each guard G in H.guards:
state = MapGuardToState(G)
active_states.add(state)
handler_state_map[H] = active_states
4. DETECT STATE TRANSITIONS
─────────────────────────
For each handler H:
pre_state = handler_state_map[H] // State required to enter
For each action A in H.actions:
If A modifies variable V:
If V is state-defining:
post_state = DeterminePostState(V, A)
Create transition: pre_state → post_state
5. VALIDATE STATE GRAPH
─────────────────────
Check for:
- Unreachable states
- Missing transitions
- Conflicting conditions
RETURN implicit_states, transitionsGuard Pattern Catalog
| Guard Pattern | Implied States | Transition Trigger |
|---|---|---|
? $X exists | #has_X, #no_X | $X becomes value |
? $X is empty | #X_empty, #X_filled | $X adds item |
? $X is "value" | #X_value for each value | $X becomes "other" |
? $X is greater than N | #X_low, #X_high | $X increases/decreases |
otherwise after guards | Default/fallback state | - |
Example: Calculator with Pending Operation
flow
machine: @calculator
on :number (api)
? $pending_operation exists
perform $pending_operation with $operand and $value
$result becomes $calculation_result
$pending_operation becomes empty
$operand becomes empty
otherwise
$operand becomes $value
on :operation (api)
? $operand exists
$pending_operation becomes $operation_type
on :equals (api)
? $pending_operation exists
perform $pending_operation with $operand and $value
$result becomes $calculation_result
$pending_operation becomes emptyGuard Analysis:
┌─────────────────────────────────────────────────────────────────────────┐
│ GUARD CONDITION EXTRACTION │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Handler: on :number │
│ Guard 1: $pending_operation exists → State: #has_pending_op │
│ Guard 2: otherwise → State: #no_pending_op │
│ │
│ Handler: on :operation │
│ Guard 1: $operand exists → State: #has_operand │
│ │
│ Handler: on :equals │
│ Guard 1: $pending_operation exists → State: #has_pending_op │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ DERIVED IMPLICIT STATES │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ #ready │
│ constraints: $operand is empty AND $pending_operation is empty │
│ description: Calculator ready for first number │
│ │
│ #has_operand │
│ constraints: $operand exists AND $pending_operation is empty │
│ description: First number entered, waiting for operation │
│ │
│ #has_pending_op │
│ constraints: $pending_operation exists │
│ description: Operation selected, waiting for second number │
│ │
└─────────────────────────────────────────────────────────────────────────┘Derived State Machine:
GUARD-DERIVED STATE MACHINE
┌────────────┐
│ #ready │ $operand = empty
│ │ $pending_op = empty
└─────┬──────┘
│
│ :number (otherwise branch)
│ $operand becomes $value
▼
┌────────────────┐
│ #has_operand │ $operand exists
│ │ $pending_op = empty
└─────┬──────────┘
│
│ :operation
│ $pending_operation becomes $op_type
▼
┌────────────────┐
│#has_pending_op │ $pending_op exists
│ │
└─────┬──────────┘
│
│ :number (guard branch)
│ or :equals
│ $pending_op becomes empty
▼
┌────────────┐
│ #ready │ (back to start)
└────────────┘Algorithm 3: Context-Derived States
Overview
Context-derived states are similar to guard-derived states but focus on mode variables - context variables that fundamentally change machine behavior without explicit guard checks in every handler.
Distinction from Guard-Derived
| Aspect | Guard-Derived | Context-Derived |
|---|---|---|
| Detection | Explicit ? condition | Variable assignment patterns |
| Scope | Per-handler | Machine-wide behavior mode |
| Example | ? $cart is empty | $mode becomes "degrees" |
Algorithm
ALGORITHM: ContextDerivedStateDetection
INPUT:
- flow_file: Parsed EventFlow AST
OUTPUT:
- mode_states: States representing operational modes
- mode_variables: Variables that define modes
PROCEDURE:
1. IDENTIFY MODE VARIABLES
────────────────────────
Criteria for mode variables:
a) Set to enumerated values: "degrees", "radians", "scientific"
b) Checked in multiple handlers
c) Changes machine behavior globally
mode_candidates = {}
For each handler H:
For each action A:
If A is "$var becomes 'string_value'":
mode_candidates[var].add(string_value)
For var in mode_candidates:
If mode_candidates[var].size >= 2:
Mark var as mode_variable
2. BUILD MODE STATE MAP
─────────────────────
For each mode_variable M:
For each value V in M.possible_values:
Create state: #{M}_{V}
Example: $angle_mode = "degrees" → #angle_mode_degrees
3. DETECT MODE TRANSITIONS
────────────────────────
For each handler H:
For each action A that sets mode_variable M:
pre_mode = current mode or "any"
post_mode = A.new_value
Create transition: #{M}_{pre} → #{M}_{post}
4. ANALYZE MODE IMPACT
────────────────────
For each handler H:
For each guard G or action A:
If G/A references mode_variable M:
Mark H as mode-dependent
Document behavior difference per mode
RETURN mode_states, mode_transitionsExample: Scientific Calculator Modes
flow
machine: @calculator
scenario: mode switching
on :set_degrees (api)
$angle_mode becomes "degrees"
on :set_radians (api)
$angle_mode becomes "radians"
on :set_gradians (api)
$angle_mode becomes "gradians"
scenario: trigonometric operations
on :sin (api)
? $angle_mode is "degrees"
$result becomes sin($value * PI / 180)
? $angle_mode is "radians"
$result becomes sin($value)
? $angle_mode is "gradians"
$result becomes sin($value * PI / 200)Context Analysis:
┌─────────────────────────────────────────────────────────────────────────┐
│ MODE VARIABLE DETECTION │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Variable: $angle_mode │
│ Possible values: "degrees", "radians", "gradians" │
│ Set by: :set_degrees, :set_radians, :set_gradians │
│ Used by: :sin, :cos, :tan (affects calculation) │
│ │
│ Classification: MODE VARIABLE ✓ │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ DERIVED MODE STATES │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ #degrees_mode │
│ constraint: $angle_mode is "degrees" │
│ entry: :set_degrees │
│ behavior: Trig functions convert degrees to radians │
│ │
│ #radians_mode │
│ constraint: $angle_mode is "radians" │
│ entry: :set_radians │
│ behavior: Trig functions use value directly │
│ │
│ #gradians_mode │
│ constraint: $angle_mode is "gradians" │
│ entry: :set_gradians │
│ behavior: Trig functions convert gradians to radians │
│ │
└─────────────────────────────────────────────────────────────────────────┘Derived State Machine:
CONTEXT-DERIVED MODE STATES
┌──────────────────────────────────────────────────┐
│ │
│ ┌────────────────┐ │
│ │ #degrees_mode │◄──── :set_degrees │
│ └───────┬────────┘ │
│ │ │
│ │ :set_radians │
│ ▼ │
│ ┌────────────────┐ │
│ │ #radians_mode │◄──── :set_radians │
│ └───────┬────────┘ │
│ │ │
│ │ :set_gradians │
│ ▼ │
│ ┌────────────────┐ │
│ │ #gradians_mode │◄──── :set_gradians │
│ └────────────────┘ │
│ │
│ Note: All modes can transition to any other │
│ mode via the set_* events │
│ │
│ Trig operations (:sin, :cos, :tan) work in │
│ ALL modes but with different behavior │
│ │
└──────────────────────────────────────────────────┘Combined Derivation Pipeline
Overview
The three algorithms are combined into a unified pipeline that produces a complete state model:
┌─────────────────────────────────────────────────────────────────────────────┐
│ COMBINED STATE DERIVATION PIPELINE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ .flow file │ │
│ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ PHASE 1: Parse & Extract │ │
│ │ ───────────────────────── │ │
│ │ • Parse flow file into AST │ │
│ │ • Extract handlers, guards, actions, emits │ │
│ │ • Build symbol table (events, actors, variables) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ PHASE 2: Event-Flow Analysis (HIGH CONFIDENCE) │ │
│ │ ────────────────────────────────────────────── │ │
│ │ • Identify emit/response patterns │ │
│ │ • Build cross-machine communication graph │ │
│ │ • Create wait states for each emit with expected response │ │
│ │ • Mark terminal states (no outgoing transitions) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ PHASE 3: Guard Analysis (MEDIUM CONFIDENCE) │ │
│ │ ─────────────────────────────────────────── │ │
│ │ • Extract all guard conditions │ │
│ │ • Identify state-defining guards (existence, value checks) │ │
│ │ • Create implicit states from guard partitions │ │
│ │ • Map handlers to their required states │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ PHASE 4: Context/Mode Analysis (MEDIUM CONFIDENCE) │ │
│ │ ────────────────────────────────────────────── │ │
│ │ • Identify mode variables (enumerated string values) │ │
│ │ • Create mode states for each possible value │ │
│ │ • Map mode transitions from setter handlers │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ PHASE 5: State Merging & Conflict Resolution │ │
│ │ ──────────────────────────────────────────── │ │
│ │ • Merge states from all three sources │ │
│ │ • Resolve naming conflicts │ │
│ │ • Handle orthogonal state dimensions (mode × workflow state) │ │
│ │ • Validate completeness │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ PHASE 6: Confidence Scoring & Ambiguity Detection │ │
│ │ ───────────────────────────────────────────── │ │
│ │ • Score each derived state by confidence │ │
│ │ • Identify ambiguous cases │ │
│ │ • Flag states that need human confirmation │ │
│ │ • Check for machine mode markers │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │.states.flow │ + confidence report │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Confidence Scoring
Each derived state receives a confidence score:
| Confidence | Score | Source | Requires Confirmation? |
|---|---|---|---|
| High | 90-100 | Event-flow patterns | No |
| Medium | 60-89 | Guard/context patterns | Optional |
| Low | 30-59 | Heuristic inference | Yes |
| Undecidable | 0-29 | No clear pattern | Yes (or mode marker) |
Conflict Resolution
When multiple derivation sources suggest different states:
CONFLICT RESOLUTION RULES:
1. EXPLICIT > IMPLICIT
If developer wrote "moves to #state", use that state name.
2. EVENT-FLOW > GUARD > CONTEXT
Higher confidence sources take precedence.
3. ORTHOGONAL DIMENSIONS
When states are independent (e.g., mode + workflow), create composite:
#degrees_mode + #awaiting_payment → #degrees_awaiting_payment
Or keep as separate state dimensions.
4. MERGE EQUIVALENT STATES
If two derived states have identical constraints and transitions,
merge them and use the more descriptive name.Comprehensive Machine Configuration Analysis
This section analyzes ALL possible machine configurations and their state derivation rules.
Configuration 1: Single Machine, Single Actor, No Scenarios (Minimal)
The simplest possible flow file:
flow
validate order detailsImplicit Structure:
flow
machine: @default // Implicit default machine
scenario: default // Implicit default scenario
on :trigger (api) // Implicit trigger event
validate order detailsState Derivation:
┌─────────────────────────────────────────────────────────────────────────┐
│ MINIMAL FLOW DERIVATION │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Input: "validate order details" │
│ │
│ Implicit elements: │
│ • Machine: @default │
│ • Scenario: default │
│ • Event: :trigger (api) │
│ │
│ Derivation: │
│ 1. Single handler → single entry point │
│ 2. No emit → no wait states │
│ 3. No guards → no partitions │
│ 4. Handler completes → terminal state │
│ │
│ Result: │
│ #idle (initial) → :trigger → #completed (terminal, success) │
│ │
│ Confidence: 100% (trivial case) │
│ │
└─────────────────────────────────────────────────────────────────────────┘Generated States:
flow
#idle
type: initial
waiting_for: :trigger
#completed
type: terminal
outcome: success
after: :triggerConfiguration 2: Single Machine, Single Actor, Single Scenario, Multiple Events
flow
machine: @order
scenario: checkout
on :add_item (api)
$items adds $item
on :remove_item (api)
$items removes $item
on :checkout (api)
process orderAnalysis:
┌─────────────────────────────────────────────────────────────────────────┐
│ SINGLE SCENARIO, MULTIPLE API HANDLERS │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Question: Are these sequential or independent? │
│ │
│ Analysis: │
│ • :add_item (api) - no guards │
│ • :remove_item (api) - no guards │
│ • :checkout (api) - no guards │
│ • No emit/response patterns │
│ • All modify $items but no guard checks │
│ │
│ Decision: NO GUARDS = INDEPENDENT │
│ │
│ All three handlers can be called at any time, in any order. │
│ They share context ($items) but don't REQUIRE prior state. │
│ │
│ Result: Single #ready state with self-loops │
│ │
│ ┌───────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌─────────┐ │ │
│ │ :add_item │ #ready │ :remove_item │ │
│ └─────────────►│ │◄─────────────────────┘ │
│ │ │ │
│ :checkout │ │ │
│ ──────────────►│ │ │
│ └─────────┘ │
│ │
│ Note: :checkout COULD be terminal, but without guards there's no │
│ structural indication it's the "final" operation. │
│ │
└─────────────────────────────────────────────────────────────────────────┘What if :checkout should be final? Add guards:
flow
on :checkout (api)
? $items is not empty // ← Guard creates implicit state
process orderNow derivation changes:
:add_itemand:remove_itemcan run anytime:checkoutrequires$items is not empty→ implies #has_items state
Configuration 3: Single Machine, Single Actor, Multiple Scenarios
flow
machine: @calculator
scenario: basic operations
on :add (api)
$result increases by $value
on :subtract (api)
$result decreases by $value
scenario: memory operations
on :memory_store (api)
$memory becomes $result
on :memory_recall (api)
$result becomes $memoryAnalysis:
┌─────────────────────────────────────────────────────────────────────────┐
│ MULTIPLE SCENARIOS - SAME MACHINE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Scenarios are DOCUMENTATION GROUPINGS, not state boundaries. │
│ │
│ From derivation perspective: │
│ • All 4 handlers are (api) entry points │
│ • No guards enforce ordering │
│ • No emit/response patterns │
│ │
│ Scenarios help humans understand related functionality: │
│ • "basic operations" = add, subtract │
│ • "memory operations" = memory_store, memory_recall │
│ │
│ But they DON'T create separate state spaces. │
│ │
│ Result: Single #ready state │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ #ready │ │
│ │ │ │
│ │ Handles: │ │
│ │ scenario: basic operations │ │
│ │ • :add, :subtract │ │
│ │ scenario: memory operations │ │
│ │ • :memory_store, :memory_recall │ │
│ │ │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘When DO scenarios affect state? When they contain sequential events with guards:
flow
scenario: checkout process
on :start_checkout (api)
$checkout_started becomes true
on :confirm_payment (api)
? $checkout_started // ← Guard creates sequence WITHIN scenario
process paymentConfiguration 4: Single Machine, Multiple Actors
flow
machine: @order
on :place_order from @customer (api)
emit :validate to @validator
on :validated from @validator
emit :charge to @payment
on :payment_success from @payment
emit :confirmation to @customerAnalysis:
┌─────────────────────────────────────────────────────────────────────────┐
│ SINGLE MACHINE, MULTIPLE ACTORS │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Actors involved: │
│ • @customer - initiates order (external) │
│ • @validator - validates order (service) │
│ • @payment - processes payment (service) │
│ │
│ Event flow: │
│ @customer ──:place_order──► @order │
│ @order ────:validate─────► @validator │
│ @validator ─:validated───► @order │
│ @order ────:charge───────► @payment │
│ @payment ──:payment_success─► @order │
│ @order ────:confirmation──► @customer │
│ │
│ Emit/Response patterns detected: │
│ 1. emit :validate to @validator → on :validated from @validator ✓ │
│ 2. emit :charge to @payment → on :payment_success from @payment ✓ │
│ │
│ Each emit creates a WAIT STATE (high confidence): │
│ │
│ #idle │
│ ↓ :place_order │
│ #awaiting_validation ← emit :validate to @validator │
│ ↓ :validated │
│ #awaiting_payment ← emit :charge to @payment │
│ ↓ :payment_success │
│ #completed ← terminal │
│ │
│ Confidence: 95% (clear emit/response patterns) │
│ │
└─────────────────────────────────────────────────────────────────────────┘Configuration 5: Multiple Machines (System)
flow
// ─── order.flow ───
machine: @order
on :checkout from @customer (api)
emit :request_payment to @payment
on :payment_success from @payment
emit :reserve_stock to @warehouse
on :stock_reserved from @warehouse
emit :confirmation to @customerflow
// ─── payment.flow ───
machine: @payment
on :request_payment from @order
process payment
? payment successful
emit :payment_success to @order
otherwise
emit :payment_failed to @orderflow
// ─── warehouse.flow ───
machine: @warehouse
on :reserve_stock from @order
check inventory
? items available
emit :stock_reserved to @order
otherwise
emit :stock_unavailable to @orderSystem-Level Analysis:
┌─────────────────────────────────────────────────────────────────────────┐
│ MULTI-MACHINE SYSTEM DERIVATION │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ STEP 1: Build Cross-Machine Communication Graph │
│ ────────────────────────────────────────────── │
│ │
│ @customer │
│ │ │
│ │ :checkout │
│ ▼ │
│ @order ◄──────────────────────────────────────────┐ │
│ │ │ │
│ │ :request_payment :payment_success │ │
│ ▼ :payment_failed │ │
│ @payment ─────────────────────────────────────────┤ │
│ │ │
│ @order ◄──────────────────────────────────────────┤ │
│ │ │ │
│ │ :reserve_stock :stock_reserved │ │
│ ▼ :stock_unavailable │ │
│ @warehouse ───────────────────────────────────────┘ │
│ │
│ STEP 2: Derive States Per Machine │
│ ───────────────────────────────── │
│ │
│ @order states (orchestrator): │
│ #idle → #awaiting_payment → #awaiting_stock → #completed │
│ ↘ #payment_failed ↘ #stock_unavailable │
│ │
│ @payment states (service): │
│ #idle → #processing → #completed │
│ (simpler - single request/response cycle) │
│ │
│ @warehouse states (service): │
│ #idle → #checking → #completed │
│ (simpler - single request/response cycle) │
│ │
│ STEP 3: Cross-Reference Validation │
│ ─────────────────────────────────── │
│ │
│ For each emit in @order: │
│ • emit :request_payment to @payment │
│ ✓ @payment has: on :request_payment from @order │
│ • emit :reserve_stock to @warehouse │
│ ✓ @warehouse has: on :reserve_stock from @order │
│ │
│ For each response to @order: │
│ • :payment_success from @payment │
│ ✓ @payment emits: emit :payment_success to @order │
│ • :stock_reserved from @warehouse │
│ ✓ @warehouse emits: emit :stock_reserved to @order │
│ │
│ All cross-machine references validated ✓ │
│ │
└─────────────────────────────────────────────────────────────────────────┘Configuration 6: Single Scenario with Multiple Waiting Events
flow
machine: @loan
scenario: loan application
on :submit from @customer (api)
emit async :check_credit to @credit_bureau
emit async :verify_identity to @identity_service
emit async :check_fraud to @fraud_service
on :credit_result from @credit_bureau
$credit_score becomes $result.score
check if all complete
on :identity_result from @identity_service
$identity_verified becomes $result.verified
check if all complete
on :fraud_result from @fraud_service
$fraud_clear becomes $result.clear
check if all complete
on :all_checks_complete
? $credit_score > 700 and $identity_verified and $fraud_clear
emit :approved to @customer
otherwise
emit :declined to @customerAnalysis:
┌─────────────────────────────────────────────────────────────────────────┐
│ PARALLEL ASYNC - MULTIPLE WAIT EVENTS │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Pattern: Fan-out / Fan-in (Scatter-Gather) │
│ │
│ After :submit, THREE parallel requests are made: │
│ • emit async :check_credit │
│ • emit async :verify_identity │
│ • emit async :check_fraud │
│ │
│ The machine enters a COLLECTING state where it waits for │
│ ALL THREE responses (in any order). │
│ │
│ State derivation: │
│ │
│ #idle │
│ ↓ :submit │
│ #collecting_results ← waiting for 3 responses │
│ ↓ (when all received) │
│ :all_checks_complete │
│ ↓ │
│ #approved OR #declined ← terminal states │
│ │
│ Key insight: Even though 3 events can arrive, │
│ there's ONE waiting state (#collecting_results) │
│ with internal tracking of which responses arrived. │
│ │
│ The "check if all complete" action is the fan-in logic. │
│ │
└─────────────────────────────────────────────────────────────────────────┘Generated States:
flow
#idle
type: initial
waiting_for: :submit from @customer
#collecting_results
type: waiting
after: :submit
waiting_for_all:
- :credit_result from @credit_bureau
- :identity_result from @identity_service
- :fraud_result from @fraud_service
collection_complete_event: :all_checks_complete
#approved
type: terminal
outcome: success
after: :all_checks_complete
when: all checks passed
#declined
type: terminal
outcome: failure
after: :all_checks_complete
when: any check failedWhy Same Scenario?
These 5 event handlers belong in the same scenario because:
- Single Business Flow: All events are part of the "loan application" process
- Causal Dependency:
:credit_result,:identity_result,:fraud_resultcannot occur without:submitfirst - Shared Outcome: All responses contribute to a single decision (approve/decline)
- Temporal Coupling: The process starts together and ends together
If these were independent operations (e.g., standalone credit check API), they would be:
- Separate machines (
@credit_bureau,@identity_service,@fraud_service) - Each with their own scenarios
┌─────────────────────────────────────────────────────────────────────────┐
│ SCENARIO GROUPING RULE │
│ │
│ Events belong in the SAME scenario when: │
│ ✓ They form a single business flow (start → ... → end) │
│ ✓ Later events DEPEND on earlier events │
│ ✓ They share context and contribute to a common outcome │
│ │
│ Events belong in SEPARATE scenarios when: │
│ ✓ They are independent operations (can be called anytime) │
│ ✓ No causal dependency between them │
│ ✓ Different business capabilities │
│ │
└─────────────────────────────────────────────────────────────────────────┘Configuration 7: Internal Events (Same Machine Communication)
flow
machine: @order
on :checkout from @customer (api)
validate cart
emit :process_payment // ← No "to @actor" = internal
on :process_payment // ← Internal handler (no from clause)
charge card
emit :send_confirmation
on :send_confirmation // ← Internal handler
send email
order moves to #completedAnalysis:
┌─────────────────────────────────────────────────────────────────────────┐
│ INTERNAL EVENTS - SAME MACHINE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Internal emit (no "to @actor") triggers handler in SAME machine. │
│ │
│ Execution model options: │
│ A) SYNC: Handler runs immediately inline │
│ B) ASYNC: Event queued, handler runs later │
│ │
│ For state derivation: │
│ • If SYNC: No wait state (all runs in one transaction) │
│ • If ASYNC: Wait state between each internal emit │
│ │
│ Default assumption: SYNC (no wait states for internal events) │
│ │
│ State derivation (sync model): │
│ │
│ #idle │
│ ↓ :checkout │
│ │ validate cart │
│ │ emit :process_payment (sync - continues inline) │
│ │ charge card │
│ │ emit :send_confirmation (sync - continues inline) │
│ │ send email │
│ │ order moves to #completed │
│ ↓ │
│ #completed │
│ │
│ Result: Only 2 states (#idle, #completed) because internal │
│ events execute synchronously within the same request. │
│ │
│ To create wait states, use: │
│ emit async :process_payment │
│ │
└─────────────────────────────────────────────────────────────────────────┘Configuration 8: Hybrid - Guards AND Emit/Response
flow
machine: @order
on :checkout from @customer (api)
? cart is not empty
? $customer.is_premium
apply premium discount
emit :request_payment to @payment
otherwise
emit :empty_cart_error to @customer
on :payment_success from @payment
? $total > 1000
emit :request_approval to @manager
otherwise
emit :confirmation to @customer
on :payment_failed from @payment
emit :checkout_failed to @customer
on :approved from @manager
emit :confirmation to @customer
on :rejected from @manager
emit :request_refund to @payment
emit :order_rejected to @customerAnalysis:
┌─────────────────────────────────────────────────────────────────────────┐
│ HYBRID: GUARDS + EMIT/RESPONSE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Multiple derivation sources combine: │
│ │
│ From GUARDS: │
│ • ? cart is not empty → #has_cart vs #empty_cart │
│ • ? $customer.is_premium → affects actions but not state │
│ • ? $total > 1000 → #needs_approval vs #auto_approved │
│ │
│ From EMIT/RESPONSE: │
│ • emit to @payment → #awaiting_payment │
│ • emit to @manager → #awaiting_approval │
│ │
│ Combined state machine: │
│ │
│ :checkout │
│ │ │
│ ┌────────────┴────────────┐ │
│ ▼ ▼ │
│ [cart not empty] [cart empty] │
│ │ │ │
│ ▼ ▼ │
│ emit :request_payment emit :empty_cart_error │
│ │ │ │
│ ▼ ▼ │
│ #awaiting_payment #checkout_failed │
│ │ (terminal) │
│ ┌─────────┴─────────┐ │
│ ▼ ▼ │
│ :payment_success :payment_failed │
│ │ │ │
│ │ ▼ │
│ │ #payment_failed (terminal) │
│ │ │
│ ├── [$total > 1000] ──────────────────┐ │
│ │ │ │
│ ▼ ▼ │
│ emit :confirmation emit :request_approval │
│ │ │ │
│ ▼ ▼ │
│ #completed (terminal) #awaiting_approval │
│ │ │
│ ┌──────────┴──────────┐ │
│ ▼ ▼ │
│ :approved :rejected │
│ │ │ │
│ ▼ ▼ │
│ #completed (t) #rejected (t) │
│ │
└─────────────────────────────────────────────────────────────────────────┘What is Actually Undecidable?
After comprehensive analysis, very few cases are truly undecidable:
Truly Undecidable Case 1: Timeout Events Without Clear Ownership
flow
on :submit (api)
emit :validate to @validator
on :validated from @validator
proceed
on :timeout // ← Whose timeout? When does it fire?
cancelWhy undecidable:
:timeouthas nofromclause - could be from system, scheduler, or another service- No clear trigger point - does it start at
:submit? How long? - No explicit connection to the validation flow
Solution: Require explicit source or scheduled event syntax
flow
on :submit (api)
emit :validate to @validator
schedule :validation_timeout after 30 seconds // ← Explicit
on :validation_timeout
cancelTruly Undecidable Case 2: Race Conditions in Parallel Responses
flow
on :start (api)
emit async :task_a to @service_a
emit async :task_b to @service_b
on :task_a_result from @service_a
process a result
on :task_b_result from @service_b
process b result
// What if both arrive at EXACTLY the same time?
// Which handler runs first? Does order matter?Why undecidable:
- The relative order of
:task_a_resultand:task_b_resultis non-deterministic - If actions affect shared state differently based on order, behavior is unpredictable
Solution: This is a runtime concern, not state derivation
- State derivation gives:
#idle→#collecting→#completed - Runtime must handle concurrent event processing
NOT Undecidable: Independent Operations
flow
machine: @calculator
on :add (api)
$result increases by $value
on :subtract (api)
$result decreases by $valueThis IS decidable:
- No guards = no sequence required
- No emit = no waiting
- Result: Single
#readystate, all handlers loop back - Confidence: 100%
Machine Mode Markers (Optional)
Mode markers are optional documentation hints. The derivation algorithm can determine machine behavior from code structure in most cases. Mode markers are useful for:
- Explicit documentation - Make intent clear to readers
- Derivation optimization - Skip analysis when you know the answer
- Edge cases - Override derivation for special cases
Important: Mode Markers Do NOT Change Behavior
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ Mode markers affect STATE DERIVATION only, not runtime behavior. │
│ │
│ These two are EQUIVALENT at runtime: │
│ │
│ machine: @calculator machine: @calculator (stateless) │
│ │
│ on :add (api) on :add (api) │
│ $result += $value $result += $value │
│ │
│ The (stateless) marker just tells the derivation algorithm: │
│ "Don't bother analyzing - I know this is a single-state machine." │
│ │
└─────────────────────────────────────────────────────────────────────────┘Syntax
flow
machine: @name (mode)Available Modes
| Mode | Meaning | When to Use |
|---|---|---|
(stateless) | Explicit single-state machine | Documentation, skip analysis |
(sequential) | Force sequential interpretation | When naming suggests sequence but guards are intentionally omitted |
| (no marker) | Full derivation algorithm | Default - let the algorithm figure it out |
When You DON'T Need Mode Markers
flow
// This calculator is automatically detected as single-state:
// - No guards
// - No emit/response patterns
// - All (api) handlers
// NO MODE MARKER NEEDED
machine: @calculator
on :add (api)
$result increases by $value
on :subtract (api)
$result decreases by $valueDerivation result (automatic): Single #ready state, confidence 100%
When Mode Markers ARE Useful
1. Documentation Clarity
flow
// The (stateless) marker documents intent:
// "This machine intentionally has no state transitions"
machine: @calculator (stateless)
on :add (api)
$result increases by $value2. Sequential Without Guards (Edge Case)
flow
// You WANT sequential behavior but intentionally skip guards
// (perhaps for a simplified prototype)
machine: @wizard (sequential)
on :step_one (api)
do first thing
on :step_two (api)
do second thing // No guard, but (sequential) forces order
on :step_three (api)
do third thingWarning: This creates a state machine that the CODE doesn't enforce. The derived states exist for documentation/diagrams, but runtime doesn't prevent calling :step_three before :step_one.
Better approach: Add guards if you want enforcement:
flow
machine: @wizard
on :step_one (api)
$step_one_done becomes true
on :step_two (api)
? $step_one_done
do second thing
on :step_three (api)
? $step_two_done
do third thingComprehensive Examples
Example 1: Basic Calculator (Stateless)
flow
machine: @calculator (stateless)
on :add (api)
$result increases by $value
on :subtract (api)
$result decreases by $valueDerivation Analysis:
┌─────────────────────────────────────────────────────────────────────────┐
│ DERIVATION ANALYSIS: Basic Calculator │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Mode: STATELESS (explicit marker) │
│ │
│ Phase 1: Event-Flow Analysis │
│ • No emit statements found │
│ • No cross-machine communication │
│ • Result: No event-flow derived states │
│ │
│ Phase 2: Guard Analysis │
│ • No guards found │
│ • Result: No guard-derived states │
│ │
│ Phase 3: Context Analysis │
│ • $result modified but no mode patterns │
│ • Result: No context-derived states │
│ │
│ Phase 4: Mode Marker Check │
│ • Mode: stateless │
│ • Result: Single state derivation │
│ │
│ FINAL RESULT: │
│ #ready (stateless) - handles all operations │
│ Confidence: 100% (explicit mode) │
│ │
└─────────────────────────────────────────────────────────────────────────┘Generated States File:
flow
// calculator.states.flow
machine: @calculator
#ready
type: stateless
description: Calculator ready for any arithmetic operation
handles: :add, :subtractExample 2: Calculator with Memory
flow
machine: @calculator
scenario: basic operations
on :add (api)
$result increases by $value
on :clear (api)
$result becomes 0
$memory becomes 0
scenario: memory operations
on :memory_store (api)
$memory becomes $result
on :memory_recall (api)
? $memory exists
$result becomes $memory
otherwise
emit :error to @user
with "No value in memory"
on :memory_clear (api)
$memory becomes 0Derivation Analysis:
┌─────────────────────────────────────────────────────────────────────────┐
│ DERIVATION ANALYSIS: Calculator with Memory │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Mode: DEFAULT (no marker) │
│ │
│ Phase 1: Event-Flow Analysis │
│ • emit :error to @user found in :memory_recall │
│ • No response handler for :error (fire-and-forget) │
│ • Result: No wait states from event-flow │
│ │
│ Phase 2: Guard Analysis │
│ • Guard found: `? $memory exists` in :memory_recall │
│ • State-defining: YES (existence check) │
│ • Derived states: │
│ - #has_memory ($memory exists) │
│ - #no_memory ($memory not set or 0) │
│ │
│ Phase 3: Context Analysis │
│ • $memory set by :memory_store │
│ • $memory cleared by :memory_clear and :clear │
│ • Pattern: binary state (has/no memory) │
│ │
│ Phase 4: Merge Analysis │
│ • Guard-derived and context-derived agree │
│ • No conflicts │
│ │
│ FINAL RESULT: │
│ #no_memory (initial) - memory empty │
│ #has_memory - memory contains value │
│ Confidence: 75% (guard-derived) │
│ │
│ NOTE: Since no handler REQUIRES a specific state to run │
│ (except :memory_recall with guard), these states are │
│ INFORMATIONAL rather than ENFORCED. │
│ │
│ RECOMMENDATION: Mark as (stateless) if states are not important │
│ │
└─────────────────────────────────────────────────────────────────────────┘Generated States File:
flow
// calculator.states.flow
machine: @calculator
#no_memory
type: initial
description: Memory is empty
constraint: $memory is empty or $memory equals 0
transitions_to: #has_memory via :memory_store
#has_memory
type: waiting
description: Memory contains a stored value
constraint: $memory exists and $memory is not 0
transitions_to: #no_memory via :memory_clear, :clearExample 3: Calculator with Pending Operation
flow
machine: @calculator
on :number (api)
? $pending_operation exists
perform $pending_operation with $operand and $value
$result becomes $calculation_result
$pending_operation becomes empty
$operand becomes $result
otherwise
$operand becomes $value
$result becomes $value
on :operation (api)
? $operand exists
$pending_operation becomes $operation_type
otherwise
emit :error to @user
with "Enter a number first"
on :equals (api)
? $pending_operation exists
? $operand exists
perform $pending_operation with $operand and $value
$result becomes $calculation_result
$pending_operation becomes empty
$operand becomes empty
on :clear (api)
$result becomes 0
$operand becomes empty
$pending_operation becomes empty
on :all_clear (api)
$result becomes 0
$operand becomes empty
$pending_operation becomes empty
$memory becomes 0Derivation Analysis:
┌─────────────────────────────────────────────────────────────────────────┐
│ DERIVATION ANALYSIS: Calculator with Pending Operation │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Phase 2: Guard Analysis │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ HANDLER: on :number │ │
│ │ │ │
│ │ Guard Path 1: $pending_operation exists │ │
│ │ → Implies state: #has_pending_op │ │
│ │ → Actions: perform calculation, update $operand │ │
│ │ → Post-state: $pending_operation becomes empty │ │
│ │ $operand becomes $result │ │
│ │ → Returns to: #has_operand │ │
│ │ │ │
│ │ Guard Path 2: otherwise ($pending_operation empty) │ │
│ │ → Implies state: #no_pending_op │ │
│ │ → Actions: $operand becomes $value │ │
│ │ → Post-state: #has_operand │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ HANDLER: on :operation │ │
│ │ │ │
│ │ Guard Path 1: $operand exists │ │
│ │ → Pre-state: #has_operand │ │
│ │ → Actions: $pending_operation becomes $operation_type │ │
│ │ → Post-state: #has_pending_op │ │
│ │ │ │
│ │ Guard Path 2: otherwise ($operand empty) │ │
│ │ → Pre-state: #ready │ │
│ │ → Actions: emit error │ │
│ │ → Post-state: #ready (unchanged) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ HANDLER: on :equals │ │
│ │ │ │
│ │ Guard: $pending_operation exists AND $operand exists │ │
│ │ → Pre-state: #has_pending_op (with operand) │ │
│ │ → Actions: perform calculation, clear all │ │
│ │ → Post-state: #ready │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ HANDLER: on :clear / :all_clear │ │
│ │ │ │
│ │ No guards - runs from any state │ │
│ │ → Pre-state: ANY │ │
│ │ → Actions: reset everything │ │
│ │ → Post-state: #ready │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
├─────────────────────────────────────────────────────────────────────────┤
│ DERIVED STATE MACHINE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ :clear / :all_clear │
│ ┌──────────────────────────────────────┐ │
│ │ │ │
│ │ │ │
│ ▼ │ │
│ ┌────────────┐ │ │
│ │ #ready │ $operand = empty │ │
│ │ │ $pending_op = empty │ │
│ └─────┬──────┘ │ │
│ │ │ │
│ │ :number (otherwise branch) │ │
│ │ $operand becomes $value │ │
│ ▼ │ │
│ ┌────────────────┐ │ │
│ │ #has_operand │ $operand exists │ │
│ │ │ $pending_op = empty │ │
│ └─────┬──────────┘ │ │
│ │ │ │
│ │ :operation │ │
│ │ $pending_op becomes $op_type │ │
│ ▼ │ │
│ ┌────────────────┐ │ │
│ │#has_pending_op │ $pending_op exists │ │
│ │ │ │ │
│ └───┬───────┬────┘ │ │
│ │ │ │ │
│ :number │ │ :equals │ │
│ (guard) │ │ (perform & clear) │ │
│ │ │ │ │
│ ▼ └─────────────────────────────────┘ │
│ ┌──────────────┐ │
│ │#has_operand │ (chain calculation, keep operand) │
│ └──────────────┘ │
│ │
│ Confidence: 85% (clear guard patterns) │
│ │
└─────────────────────────────────────────────────────────────────────────┘Generated States File:
flow
// calculator.states.flow
machine: @calculator
#ready
type: initial
description: Calculator cleared, ready for first number
constraint: $operand is empty AND $pending_operation is empty
waiting_for: :number, :clear, :all_clear
#has_operand
type: waiting
description: First number entered, waiting for operation
constraint: $operand exists AND $pending_operation is empty
after: :number (when no pending operation)
waiting_for: :operation, :number, :clear, :all_clear
#has_pending_op
type: waiting
description: Operation selected, waiting for second number
constraint: $pending_operation exists
after: :operation
waiting_for: :number, :equals, :clear, :all_clearExample 4: Order Processing (Event-Flow Derived)
flow
machine: @order
on :checkout from @customer (api)
validate cart
emit :request_payment to @payment
with $order_id, $total
on :payment_success from @payment
emit :reserve_stock to @warehouse
with $order_id, $items
on :payment_failed from @payment
emit :checkout_failed to @customer
on :stock_reserved from @warehouse
emit :confirmation to @customer
emit :schedule_delivery to @shipping
on :stock_unavailable from @warehouse
emit :request_refund to @payment
emit :out_of_stock to @customer
on :refund_complete from @payment
// Order fully cancelled
on :delivery_scheduled from @shipping
// Order completeDerivation Analysis:
┌─────────────────────────────────────────────────────────────────────────┐
│ DERIVATION ANALYSIS: Order Processing │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Phase 1: Event-Flow Analysis (HIGH CONFIDENCE) │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ EMIT/RESPONSE PATTERN 1: │ │
│ │ │ │
│ │ :checkout │ │
│ │ │ │ │
│ │ └── emit :request_payment to @payment │ │
│ │ │ │ │
│ │ ├── on :payment_success from @payment ✓ │ │
│ │ └── on :payment_failed from @payment ✓ │ │
│ │ │ │
│ │ CREATES: #awaiting_payment │ │
│ │ Confidence: 95% │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ EMIT/RESPONSE PATTERN 2: │ │
│ │ │ │
│ │ :payment_success │ │
│ │ │ │ │
│ │ └── emit :reserve_stock to @warehouse │ │
│ │ │ │ │
│ │ ├── on :stock_reserved from @warehouse ✓ │ │
│ │ └── on :stock_unavailable from @warehouse ✓ │ │
│ │ │ │
│ │ CREATES: #awaiting_stock │ │
│ │ Confidence: 95% │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ EMIT/RESPONSE PATTERN 3: │ │
│ │ │ │
│ │ :stock_unavailable │ │
│ │ │ │ │
│ │ └── emit :request_refund to @payment │ │
│ │ │ │ │
│ │ └── on :refund_complete from @payment ✓ │ │
│ │ │ │
│ │ CREATES: #awaiting_refund │ │
│ │ Confidence: 95% │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ EMIT/RESPONSE PATTERN 4: │ │
│ │ │ │
│ │ :stock_reserved │ │
│ │ │ │ │
│ │ └── emit :schedule_delivery to @shipping │ │
│ │ │ │ │
│ │ └── on :delivery_scheduled from @shipping ✓ │ │
│ │ │ │
│ │ CREATES: #awaiting_delivery │ │
│ │ Confidence: 95% │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ TERMINAL STATES: │
│ • :payment_failed → #checkout_failed (failure) │
│ • :refund_complete → #refunded (failure) │
│ • :delivery_scheduled → #completed (success) │
│ │
│ Overall Confidence: 95% (all event-flow derived) │
│ │
└─────────────────────────────────────────────────────────────────────────┘Generated State Diagram:
ORDER STATE MACHINE
┌────────────┐
│ #idle │
│ (initial) │
└─────┬──────┘
│ :checkout
▼
┌──────────────────┐
│#awaiting_payment │◄── emit :request_payment to @payment
│ (waiting) │
└────────┬─────────┘
│
┌────────┴────────────────────────┐
│ │
▼ ▼
:payment_success :payment_failed
│ │
▼ ▼
┌──────────────────┐ ┌────────────────┐
│ #awaiting_stock │ │#checkout_failed│
│ (waiting) │ │(terminal:fail) │
└────────┬─────────┘ └────────────────┘
│
┌────────┴────────────────────────┐
│ │
▼ ▼
:stock_reserved :stock_unavailable
│ │
▼ ▼
┌────────────────────┐ ┌──────────────────┐
│#awaiting_delivery │ │ #awaiting_refund │
│ (waiting) │ │ (waiting) │
└────────┬───────────┘ └────────┬─────────┘
│ │
▼ ▼
:delivery_scheduled :refund_complete
│ │
▼ ▼
┌────────────────┐ ┌────────────────┐
│ #completed │ │ #refunded │
│(terminal:pass) │ │(terminal:fail) │
└────────────────┘ └────────────────┘Generated States File:
flow
// order.states.flow
machine: @order
#idle
type: initial
description: No order started
waiting_for: :checkout from @customer
#awaiting_payment
type: waiting
description: Order submitted, waiting for payment result
after: :checkout
emits: :request_payment to @payment
waiting_for: :payment_success, :payment_failed from @payment
#checkout_failed
type: terminal
outcome: failure
description: Payment failed, order cancelled
after: :payment_failed from @payment
#awaiting_stock
type: waiting
description: Payment received, checking inventory
after: :payment_success from @payment
emits: :reserve_stock to @warehouse
waiting_for: :stock_reserved, :stock_unavailable from @warehouse
#awaiting_refund
type: waiting
description: Stock unavailable, processing refund
after: :stock_unavailable from @warehouse
emits: :request_refund to @payment
waiting_for: :refund_complete from @payment
#refunded
type: terminal
outcome: failure
description: Order cancelled, customer refunded
after: :refund_complete from @payment
#awaiting_delivery
type: waiting
description: Stock reserved, scheduling delivery
after: :stock_reserved from @warehouse
emits: :schedule_delivery to @shipping
waiting_for: :delivery_scheduled from @shipping
#completed
type: terminal
outcome: success
description: Order delivered successfully
after: :delivery_scheduled from @shippingCLI Commands
derive-states Command
bash
# Interactive mode (default)
eventflow derive-states order.flow
# Non-interactive mode (CI/CD)
eventflow derive-states order.flow --no-interactive
# Update existing states file
eventflow derive-states order.flow --update
# Show derivation analysis without generating
eventflow derive-states order.flow --analyze
# Set minimum confidence threshold
eventflow derive-states order.flow --min-confidence 70
# Force regeneration, overwrite existing
eventflow derive-states order.flow --forceanalyze-states Command
bash
# Show detailed derivation analysis
eventflow analyze-states order.flow
# Output format options
eventflow analyze-states order.flow --format json
eventflow analyze-states order.flow --format markdown
# Show only specific derivation type
eventflow analyze-states order.flow --type event-flow
eventflow analyze-states order.flow --type guard-derived
eventflow analyze-states order.flow --type context-derivedExample CLI Output
bash
$ eventflow derive-states calculator.flow --analyze
╔══════════════════════════════════════════════════════════════════════════════╗
║ STATE DERIVATION ANALYSIS: calculator.flow ║
╚══════════════════════════════════════════════════════════════════════════════╝
Machine: @calculator
Mode: DEFAULT (no marker)
───────────────────────────────────────────────────────────────────────────────
PHASE 1: Event-Flow Analysis
───────────────────────────────────────────────────────────────────────────────
Emit statements found: 1
• emit :error to @user (line 15) - fire-and-forget, no wait state
Cross-machine patterns: 0
Wait states derived: 0
───────────────────────────────────────────────────────────────────────────────
PHASE 2: Guard Analysis
───────────────────────────────────────────────────────────────────────────────
Guards found: 4
┌─ Handler: on :number ─────────────────────────────────────────────────────┐
│ Guard: ? $pending_operation exists │
│ Type: EXISTENCE CHECK │
│ Creates states: #has_pending_op, #no_pending_op │
│ Confidence: 85% │
└───────────────────────────────────────────────────────────────────────────┘
┌─ Handler: on :operation ──────────────────────────────────────────────────┐
│ Guard: ? $operand exists │
│ Type: EXISTENCE CHECK │
│ Creates states: #has_operand, #no_operand │
│ Confidence: 85% │
└───────────────────────────────────────────────────────────────────────────┘
Guard-derived states: 3
• #ready ($operand empty, $pending_op empty)
• #has_operand ($operand exists, $pending_op empty)
• #has_pending_op ($pending_op exists)
───────────────────────────────────────────────────────────────────────────────
PHASE 3: Context Analysis
───────────────────────────────────────────────────────────────────────────────
Mode variables: 0
Context-derived states: 0
───────────────────────────────────────────────────────────────────────────────
SUMMARY
───────────────────────────────────────────────────────────────────────────────
Total states: 3
Derivation source:
• Event-flow: 0
• Guard-derived: 3
• Context-derived: 0
Overall confidence: 85%
┌─ RECOMMENDATION ──────────────────────────────────────────────────────────┐
│ │
│ The derived states look complete. Run without --analyze to generate │
│ calculator.states.flow │
│ │
└───────────────────────────────────────────────────────────────────────────┘
? Generate states file? (Y/n):Decision Matrix: Quick Reference
When Does Each Derivation Source Apply?
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ STATE DERIVATION DECISION MATRIX │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ CODE PATTERN │ DERIVATION │ CONFIDENCE │ RESULT │
│ ──────────────────────────────────────┼─────────────────────┼────────────┼────────│
│ emit :X to @Y + on :Z from @Y │ Event-Flow │ HIGH (95%) │ Wait │
│ emit async :X + response handlers │ Event-Flow │ HIGH (95%) │ Wait │
│ (queued api) │ Event-Flow │ HIGH (95%) │ Wait │
│ ──────────────────────────────────────┼─────────────────────┼────────────┼────────│
│ ? $var exists │ Guard-Derived │ MED (85%) │ Branch │
│ ? $var is "value" │ Guard-Derived │ MED (85%) │ Branch │
│ ? condition + otherwise │ Guard-Derived │ MED (85%) │ Branch │
│ ──────────────────────────────────────┼─────────────────────┼────────────┼────────│
│ $mode becomes "X" (enum values) │ Context-Derived │ MED (80%) │ Mode │
│ Multiple mode handlers │ Context-Derived │ MED (80%) │ Mode │
│ ──────────────────────────────────────┼─────────────────────┼────────────┼────────│
│ Multiple (api), no guards, no emit │ Auto: Single State │ HIGH(100%) │ Ready │
│ Single action only │ Auto: Init→Terminal │ HIGH(100%) │ Simple │
│ ──────────────────────────────────────┼─────────────────────┼────────────┼────────│
│ :timeout without from/scheduled │ UNDECIDABLE │ LOW (20%) │ Ask │
│ ──────────────────────────────────────┼─────────────────────┼────────────┼────────│
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘Configuration Quick Reference
| Configuration | Example | States | Confidence |
|---|---|---|---|
| Single action | validate order | 2 (idle → done) | 100% |
| Multiple (api), no guards | Calculator | 1 (#ready) | 100% |
| Multiple (api), with guards | Wizard with guards | N (guard-derived) | 85% |
| Single machine, emit to actor | Order → Payment | N (wait states) | 95% |
| Multi-machine system | Order/Payment/Warehouse | N per machine | 95% |
| Parallel async (fan-out) | Loan checks | 1 collecting + terminals | 90% |
| Internal events (sync) | Chained handlers | Collapsed | 90% |
| Mode variables | Scientific calculator | N modes | 80% |
The Golden Rule
┌─────────────────────────────────────────────────────────────────────────┐
│ │
│ THE GOLDEN RULE │
│ │
│ "If you can call handler B without calling handler A first, │
│ then A and B are independent and share the same state." │
│ │
│ The CODE decides this, not the developer's intention. │
│ │
│ Want sequential? Add guards. │
│ Want waiting? Add emit/response. │
│ Want modes? Add mode variable checks. │
│ │
│ No guards + No emit = Independent = Single state. │
│ │
└─────────────────────────────────────────────────────────────────────────┘Migration Path
Phase 1: Introduce v2 Derivation
- Implement combined derivation pipeline
- Add
--analyzeflag for transparency - Support machine mode markers
- Maintain backward compatibility with
moves to
Phase 2: Encourage Adoption
- Add warnings for ambiguous cases
- Suggest mode markers where appropriate
- Provide automated refactoring tools
- Update documentation with new examples
Phase 3: Gradual Transition
- Allow mixed explicit/implicit states
- Validate derived states against explicit ones
- Provide migration reports
Phase 4: Full Integration
- Make derivation the default
moves tobecomes optional override- Generated
.states.flowbecomes source of truth for diagrams
Scenario Design Guidelines
Understanding when events belong in the same scenario vs. separate scenarios is crucial for proper machine design.
The Scenario Definition
A scenario groups events that form a single business flow. It's not just documentation - it represents a cohesive process with:
- A clear starting point (entry event)
- A defined progression (intermediate events)
- Terminal outcomes (success/failure states)
When to Use SAME Scenario
Events belong in the same scenario when:
| Criterion | Example | Reasoning |
|---|---|---|
| Causal dependency | :checkout → :payment_received | Payment can't happen without checkout |
| Single business flow | Loan: submit → checks → decision | One process from start to finish |
| Shared context | All events use $order_id, $total | Data flows through the process |
| Common outcome | All paths lead to #approved or #declined | Single decision point |
| Temporal coupling | Fan-out/fan-in parallel events | Start and end together |
flow
// CORRECT: Single flow, same scenario
scenario: complete purchase
on :checkout from @customer (api)
emit :request_payment to @payment
on :payment_success from @payment
emit :reserve_stock to @warehouse
on :stock_reserved from @warehouse
emit :confirmation to @customerWhen to Use SEPARATE Scenarios
Events belong in separate scenarios when:
| Criterion | Example | Reasoning |
|---|---|---|
| Independent operations | Calculator: add, subtract | Can call in any order |
| No causal dependency | CRUD operations | Each stands alone |
| Different capabilities | "cart management" vs "checkout" | Distinct business functions |
| Reusable operations | "add to cart" used by multiple flows | Shared utility |
flow
// CORRECT: Independent operations, separate scenarios
machine: @calculator
scenario: addition
on :add (api)
$result increases by $value
scenario: subtraction
on :subtract (api)
$result decreases by $value
scenario: memory operations
on :memory_store (api)
$memory becomes $result
on :memory_recall (api)
$result becomes $memoryThe Scenario Decision Tree
┌─────────────────────────────────────────────────────────────────────────────────┐
│ SCENARIO DESIGN DECISION TREE │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Q1: Can event B happen WITHOUT event A happening first? │
│ │ │
│ ├── YES → Different scenarios (independent operations) │
│ │ │
│ └── NO → Continue to Q2 │
│ │ │
│ Q2: Do events A and B share context and outcome? │
│ │ │
│ ├── YES → Same scenario (single flow) │
│ │ │
│ └── NO → Different scenarios (separate concerns) │
│ │
│ EXAMPLES: │
│ │
│ :checkout → :payment_received │
│ Q1: Can payment happen without checkout? NO │
│ Q2: Share context ($order_id, $total) and outcome (#paid)? YES │
│ → SAME SCENARIO ✓ │
│ │
│ :add → :subtract (calculator) │
│ Q1: Can subtract happen without add? YES │
│ → DIFFERENT SCENARIOS ✓ │
│ │
│ :add_to_cart → :checkout │
│ Q1: Can checkout happen without add_to_cart? NO (cart must have items) │
│ Q2: Different capabilities (cart mgmt vs purchase)? YES │
│ → DIFFERENT SCENARIOS (but checkout depends on cart state) ✓ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘Scenario vs. Machine Boundary
Sometimes the question isn't "same or different scenario" but "same or different machine":
| Situation | Solution |
|---|---|
| Independent service with its own lifecycle | Separate machine |
| Reusable capability called by multiple flows | Separate machine |
| Tightly coupled steps in one process | Same machine, same scenario |
| Related but independent operations | Same machine, different scenarios |
flow
// Payment is a SEPARATE MACHINE (independent service)
machine: @payment
scenario: process payment
on :request_payment from @order
process with gateway
? successful
emit :payment_success to @order
otherwise
emit :payment_failed to @orderImpact on State Derivation
Scenario boundaries do not affect state derivation directly, but they provide important context:
- Same scenario, sequential events → Derived states between events
- Same scenario, parallel events → Single collecting state (fan-out/fan-in)
- Different scenarios, no guards → Single shared #ready state
- Different scenarios, with guards → Guard-derived states
The derivation algorithm looks at code structure (guards, emit/response patterns), not scenario boundaries. Scenarios help humans understand the design intent.
Open Questions for Discussion
Orthogonal State Dimensions: When mode states and workflow states coexist, should they be:
- Merged into composite states (
#degrees_awaiting_payment) - Kept as separate dimensions (parallel state machines)
- Left to developer choice
- Merged into composite states (
Internal Event Execution Model: Should internal events (no
to @actor) be:- Sync by default (current assumption)
- Async by default (queue-based)
- Configurable via syntax (
emit sync :eventvsemit async :event)
Guard Complexity Limit: How deep should guard-derived state analysis go?
- Limit nesting depth (e.g., max 3 levels)
- Limit total states per handler (e.g., max 8)
- Warn but allow unlimited
Scenario Semantics:
Should scenarios affect state derivation?RESOLVED- Answer: Scenarios do NOT affect state derivation (code structure does)
- Scenarios group events that form a single business flow
- See Scenario Design Guidelines for detailed guidance
Related Documents
- IMPLICIT_STATES_PROPOSAL.md - Original (rejected) proposal
- LANE_STATE_DIAGRAMS_PROPOSAL.md - Diagram generation
- STATIC_ANALYSIS_PROPOSAL.md - State reachability analysis
Changelog
| Version | Date | Changes |
|---|---|---|
| v2.2 | 2025-12-18 | Added "Scenario Design Guidelines" section, clarified when events belong in same vs. separate scenarios, resolved Open Question 4, added "Why Same Scenario?" explanation to Configuration 6 |
| v2.1 | 2025-12-16 | Comprehensive machine configuration analysis, corrected "ambiguity" analysis (calculator IS decidable), added decision matrix, updated mode markers as optional |
| v2.0 | 2025-12-16 | Initial v2 proposal with three-algorithm approach |