Keep a TLA+ specification of a state machine or protocol in your flow. The TLC model checker tries every order of steps the specification allows and returns the shortest one that breaks a rule. Events recorded from a real run can be checked against the same design.
Optional plugin.reflow init --upgrade TLA adds it to an application and downloads it once for your platform. It brings its own Java runtime, so there is nothing else to install.
app.reflow.io
reflow / TLA · plugin lockRecorded plugin output
Flow executionAgent review
Two recorded flowsLine 6 · selected step
3# Second flow, one step: two CLI releases take turnsCurrent line
4shell.bash command="bash \"$REFLOW_FLOW_FILES/record-upgrades.sh\"" timeout=20mCurrent line
Exact RFL from two flows: the first is meant to fail; the second records two CLI releases and checks the recording twice. Comment lines are presentation. Select a checkpoint line to inspect its output; preceding lines provide context.
Output · selected step
PluginLock.tlaflow file · excerpt
Upgrade(c) ==
/\ OffersUpgrade(c)
/\ lock' = Bundle(c)
/\ last' = c.id
/\ UNCHANGED catalog
Next == \E c \in Team : Upgrade(c)
...
Quiet == \A c \in Team : ~OffersUpgrade(c)
Stabilises == <>[]Quiet
...
TeamOldRule == {Main("A", 1, "old"), Main("B", 2, "old")}
A’s CLI is built from catalog row 1 and bundles Browser build 1; B’s is built from row 2 and bundles build 2. Under the old rule a CLI offers the upgrade whenever a locked build differs from its own. Stabilises says that, in the end, nobody is offered an upgrade again.
Old rule settlesstep 1 · failed
Plugin TLA.check failed: temporal property Stabilises is violated: counterexample of 3 steps, then back to step 2, for ever (PluginLock.tla with PluginLock.old-rule.cfg)
Counterexample: 3 steps, then back to step 2, for ever
Step 1Initial state
Browser
1
Mailbox
1
Step 2Upgrade · B
Browser
1 → 2
Mailbox
1
Step 3Upgrade · A
Browser
2 → 1
Mailbox
1
then back to step 2, for ever
B’s CLI moves Browser to build 2, A’s moves it back, and B is offered the upgrade again. The lock never settles.
Accepted. The 4 lines of the trace, in order, are a behaviour of the spec.
Old-rule configuration · matched 4 of 4 lines. R1 and R2 are the two CLI releases; builds are numbered by first appearance: Browser 5e18e95 is 1, 4b3ccd8 is 2; Mailbox d10395d is 1, 4118194 is 2.
tla.trace · new ruleexpectRejection=3 · succeeded
Rejected at line 3, as this step expects. The 2 lines before it are a behaviour of the spec; no step of the spec leads from there to line 3.
Under the new rule a CLI uses the catalog history it carries to tell an older build from a newer one, and offers no upgrade while the lock holds a newer build.
Review pointAt line 3 the older release takes the lock back to its own builds, as A does in step 3 of the counterexample. The new rule never offers that upgrade.
Recorded TLA plugin output from two flows of the plugin-lock example: one meant to fail, and one step in which LocalBash ran two CLI releases against a scratch application. Values are copied from the run pages; the specification is an excerpt and the layout is illustrative.
A journey test runs one order. TLC tries them all.
Use TLA for the orders a journey test cannot stage: two teammates on different releases, a retry that crosses a crash, a message that arrives late.
The design travels in the flow.
The specification and its configurations are blocks of the flow, named in the step. TLC gets them from the flow, never from a checkout, so a flow saved in Reflow runs the same check on any device, and the step reruns exactly when the flow changes.
Every order, within bounds.
TLC explores every state the model reaches within the bounds its configuration sets. When an invariant or property breaks, the step fails, names what broke and keeps the shortest counterexample.
Then check what really ran.
A journey can write one line for each step the program takes. tla.trace checks those lines against the same specification and names the first line no behaviour of the design reaches.
Read the failure step by step.
A violated step keeps the counterexample: each step, the action that led to it and what changed. A property that must hold for ever, such as “the lock settles”, ends by naming the step it returns to.
In the example, each teammate’s CLI offers an upgrade whenever a locked build differs from the one it bundles. TLC finds the loop in a model of 8 distinct states; staging it as a journey would take two people on two releases.
The counterexample as text, and every state in full as JSON
Everything TLC printed
The exact specification and configuration bytes TLC checked
A specification is someone’s reading of the code, and it keeps passing when the code changes. tla.trace checks events recorded from a real run against it: line 1 must be an initial state, and every later line a step of the specification. A rejected recording names the first line no behaviour reaches.
In the example, one step runs two CLI releases in turn against a scratch application and records the lock after each upgrade. Under the old rule all four lines are a behaviour of the specification, so the model describes what those releases do. Under the new rule, where a CLI uses the catalog history it carries to tell an older build from a newer one, the same recording is rejected at line 3, where the older release moves the lock back.
expectViolation and expectRejection keep a known fault on record: the step passes only while TLC still finds it.
When a change is a state machine, a protocol, retries or ownership, your agent can write the specification beside a journey flow of the same behaviour, and check that journey’s recorded events with tla.trace.
TLA is not in the CLI download. This command adds it to an application and downloads it once for your platform, 54 to 59 MB, checked against the release manifest. It carries TLC 1.8.0, built from the TLA+ source, and its own Java runtime, so there is nothing else to install. Teammates and CI install it with plain reflow init, because the application’s lock names it.
What it does not check.
What a user sees. TLA says nothing about screens, and it replaces no journey test.
Large ranges of values. TLC checks the model its configuration bounds, and time and memory grow steeply with constants. A pass says nothing about larger ones.
A specification nobody keeps. It is someone’s reading of the code and keeps passing when the code changes, unless a recorded run is checked against it.
Steps from the plugin’s example flows and documentation; ... marks parts of the specification left out, and the flow also carries PluginLock.trace.cfg. The binding takes no configuration.