TLA+ plugin
Use TLA to check a design: a state machine or a protocol written as a TLA+ specification. TLC, the TLA+ model checker, tries every order of steps the specification allows, within the bounds its configuration sets, and returns the shortest sequence that breaks a rule. A journey test cannot stage most of those orders: two teammates on different releases, a retry that crosses a crash, a message that arrives late.
It checks the design, not the code. A specification is someone’s reading of the
code, and it keeps passing when the code changes. Two things tie it to the code:
a journey flow that exercises the same behaviour, and tla.trace,
which checks events recorded from a real run against the specification. TLA says
nothing about what a user sees, and it replaces no journey test.
Install
Section titled “Install”TLA is an optional plugin. It carries its own Java runtime, so it is not inside
the CLI download. reflow init downloads it once for your platform from the
release your CLI was installed from, checks it against that release’s manifest
and installs it. Plan and apply never download.
Add it to an application that already has a plugin selection:
reflow init --upgrade TLA --collection <collection-id>The other selected plugins stay exactly as locked. On an application with no
selection yet, reflow init TLA --collection <collection-id> selects TLA alone;
name the other plugins you need in the same command. A teammate’s device, or CI,
installs it with plain reflow init, because the application’s lock names it.
Every device of the application needs a CLI release that knows TLA.
Without a network connection, init stops, changes nothing and names the download that failed. Run it again when the release is reachable. No Java needs to be installed, and none on the machine is used.
Connect
Section titled “Connect”The binding takes no configuration:
{ "tla": {"provider": "TLA", "configuration": {}}}chmod 600 /absolute/path/to/bindings.jsonreflow target --group design-checks --scope device --collection <collection-id> --bindings /absolute/path/to/bindings.jsonThe flow carries the specification
Section titled “The flow carries the specification”A TLA step reads only files its flow carries. Put the specification and each
configuration in the flow as a fenced block whose info string ends in
file="NAME", and name the file in the step:
---name: Counter designproviders: tla: TLA---
```rfl step="The counter never passes its limit"tla.check spec="Counter.tla" config="Counter.cfg"```
```tla file="Counter.tla"---- MODULE Counter ----EXTENDS NaturalsVARIABLE countInit == count = 0Next == count < 3 /\ count' = count + 1Limit == count <= 3====```
```cfg file="Counter.cfg"INIT InitNEXT NextINVARIANT LimitCHECK_DEADLOCK FALSE```TLC sees every .tla file of the flow, so a specification can EXTENDS another
file of the flow. A flow carries at most 8 files, 64 KiB each and 192 KiB in all.
A path on the machine or in a checkout is refused, with the block to add: a flow
saved in Reflow runs where there is no checkout. Because the files are part of the
flow, a step reruns exactly when the flow changes.
Check a specification
Section titled “Check a specification”tla.check spec="PluginLock.tla" config="PluginLock.guarded.cfg"The step passes when every invariant and property the configuration lists holds in every reachable state of the model. Otherwise it fails and names what broke.
| Argument | Meaning |
|---|---|
spec | The module to check: a .tla file of the flow. Required. |
config | The TLC configuration: a .cfg file of the flow. Default: spec with .cfg. |
workers | TLC worker threads, 1 to 64. Default 1. |
heapMb | Java heap in MiB, 64 to 65536. Default 1024. |
diskMb | Limit on TLC’s working files in MiB, 64 to 65536. Default 2048. |
deadlock | check (default) reports a state with no enabled action; ignore does not. |
expectViolation | The step passes only when TLC violates exactly this invariant or property, or Deadlock. |
What a step can end as:
| Outcome | Meaning |
|---|---|
| holds | TLC explored every reachable state and found no violation. |
| violated | An invariant, a property, an assertion or the deadlock check failed. The step keeps the counterexample. |
| spec error | TLC cannot parse or evaluate the specification or its configuration. The error names the file and line, for example PluginLock.tla:42:7. |
| refused | The request was not run: a name that is not a file of the flow, an argument out of range, or a module the plugin refuses. |
| no verdict | TLC did not finish: it ran out of memory (heapMb) or disk (diskMb), or crashed. Nothing was decided; the message says what to change. |
A statement that runs out of time fails as any timed-out step does, and the
message says how many states TLC had found. A plugin call gets 30 seconds unless
the statement has timeout=, for example timeout=10m. While TLC runs, the step
shows its progress every five seconds.
expectViolation="Name" turns the step round: it passes only while TLC still
violates exactly that invariant or property. Use it to keep a known design fault
on record, or to show that a model is not passing because nothing happens in it.
TLC gets a fixed seed and fingerprint function. With workers=1 the result and
the counterexample are the same on every run. With more workers the verdict is the
same, but TLC may report another counterexample of the same property.
Read a counterexample
Section titled “Read a counterexample”A violated step’s tile is a table of the counterexample: each step, the action that led to it and what changed. A counterexample of a property that must hold for ever, such as “the lock settles”, ends by saying which step it returns to. The step’s report holds the whole table; its files are:
| File | Holds |
|---|---|
counterexample.txt | The counterexample as text: each step, its action and what changed. |
counterexample.json | Every state in full, as TLC writes it with -dumpTrace json. |
tlc-output.txt | Everything TLC printed. |
spec.tla, model.cfg | The exact bytes TLC checked. |
For example, the old plugin-lock upgrade rule, where a CLI offered an upgrade whenever a locked plugin differed from the one it bundles, fails like this:
temporal property Stabilises is violated (PluginLock.tla with PluginLock.old-rule.cfg)
1. Initial state lock = {"Browser":1,"Mailbox":1} last = "nobody"2. Upgrade {"c":{"id":"B","at":2,"rule":"old","own":{"Browser":0,"Mailbox":0}}} lock.Browser: 1 → 2 last: "nobody" → "B"3. Upgrade {"c":{"id":"A","at":1,"rule":"old","own":{"Browser":0,"Mailbox":0}}} lock.Browser: 2 → 1 last: "B" → "A"
then back to step 2, for everTeammate B’s release moves Browser forward, A’s moves it back, and B is offered the upgrade again: the lock never settles. (The first state also lists the catalog history the model checked; it is left out here.)
Check recorded events
Section titled “Check recorded events”tla.trace checks that recorded events are a behaviour of the specification:
line 1 must be an initial state, and every later line a step of the
specification that ends in the values the line records.
tla.trace spec="PluginLock.tla" config="PluginLock.trace.cfg" trace="upgrade.ndjson"The events are JSON Lines, one object per line, with these keys:
| Key | Meaning |
|---|---|
state | Required. The specification’s variables and their values after this line’s event. |
event | Optional. The action of the specification this line is a step of. Without it, any step. |
args | Optional. That action’s arguments, in order. |
note | Optional. Ignored. |
{"state": {"lock": {"Browser": 1, "Mailbox": 1}, "last": "nobody"}}{"state": {"lock": {"Browser": 2, "Mailbox": 1}, "last": "B"}}A JSON string is a TLA+ string, an integer an integer, an array a sequence and an
object a record. {"$set": [1, 2]} writes a set, {"$model": "A"} a model value,
and {"$fn": [[1, "a"]]} a function. Names in state are the specification’s
variables and values are its values: when the program’s values differ, such as a
commit hash where the specification has a number, the program that writes the
events translates them. A file holds at most 100,000 lines and 8 MiB. Over
20,000 lines, a rejected line is compared with the line before it, not with what
the specification reaches there.
| Argument | Meaning |
|---|---|
spec, config | As for tla.check. The configuration gives the constants, INIT and NEXT, and its invariants are checked on every matching state. |
trace | The events: a .ndjson or .jsonl file of the flow, or step:NAME (below). Required. |
init, next | The initial predicate and next-state action, when the configuration names a SPECIFICATION instead. |
stuttering | refuse (default) or allow: whether a line without an event may also be a step that changes nothing. |
expectRejection | A line number: the step passes only when the recording is rejected at that line. |
workers, heapMb, diskMb | As for tla.check. |
A variable a line leaves out is not checked on that line: TLC looks for any value
the specification allows. So the less a recording holds, the more it accepts. Each
line is exactly one step; a line where nothing changed is refused unless
stuttering="allow", and when the program takes several steps between two
recorded lines, record each of them.
A rejected recording names the first line no behaviour reaches, what it records against the state before it, and what the specification reaches there instead, or that its event is not possible there:
line 4 of moved-back.ndjson is not a step of PluginLock.tla: the spec can take no step after the 3 lines before it:it records last: "C" → "A"; lock.Browser: 2 → 1; lock.Mailbox: 2 → 1expectRejection=4 passes only while the recording is rejected at line 4.
Record and check in one step
Section titled “Record and check in one step”The events can be a flow file, or a file an earlier statement of the same step
wrote into the step’s private directory, $REFLOW_STEP_FILES. Name it with
step::
shell.bash command="./record-upgrades.sh > \"$REFLOW_STEP_FILES/upgrade.ndjson\""tla.trace spec="PluginLock.tla" config="PluginLock.trace.cfg" trace="step:upgrade.ndjson"The directory is empty when a step starts and is emptied when it ends, so record and check in the same step. It holds at most 64 MiB, and its files are not evidence.
Worked example: the plugin lock
Section titled “Worked example: the plugin lock”Reflow’s own plugin lock is a
design where order matters. A lock names one build of each plugin and nothing
that orders two builds, so a CLI reads the catalog history it carries to tell an
older build from a newer one. Teammates on different CLI releases each run the
reflow init --upgrade their CLI offers. The lock must settle, and it must never
move back to an older build.
PluginLock.tla models that rule: a catalog history, CLIs built from its rows,
and a lock that each CLI moves to the builds it bundles when its plan offers the
upgrade. One more rule keeps a catalog from pointing a plugin back to a build a
later one replaced (a reverted repin). The flow carries the specification and
three configurations, and checks every catalog history of three commits at once:
---name: Plugin lock catalog pins never returnproviders: tla: TLA---
```rfl step="With the guard, no catalog history moves the lock back"tla.check spec="PluginLock.tla" config="PluginLock.guarded.cfg"```
```rfl step="Upgrades happen in the guarded model"tla.check spec="PluginLock.tla" config="PluginLock.guarded-moves.cfg" expectViolation="LockNeverChanges"```
```rfl step="Without the guard some catalog history moves the lock back"tla.check spec="PluginLock.tla" config="PluginLock.unguarded.cfg" expectViolation="NeverMovesBack"```
```tla file="PluginLock.tla"---- MODULE PluginLock ----...Upgrade(c) == /\ OffersUpgrade(c) /\ lock' = Bundle(c) /\ last' = c.id /\ UNCHANGED catalog...Guarded(cat) == \A p \in Plugins, j \in 2..Len(cat) : ~Returns(cat, p, j)GuardedCatalogs == {cat \in EveryCatalog : Guarded(cat)}...NeverMovesBack == [][\A p \in Plugins : Age(p, lock'[p]) >= Age(p, lock[p])]_varsStabilises == <>[]Quiet====```
```cfg file="PluginLock.guarded.cfg"SPECIFICATION SpecCONSTANTS CatalogChoices <- GuardedCatalogs Team <- TeamNewRuleINVARIANTS TypeOK AdviceCanBeFollowedPROPERTIES Stabilises NeverMovesBackCHECK_DEADLOCK FALSE```(The other two configurations are blocks like the last one; ... marks parts of
the specification left out here.) The first step passes: over all 49 histories
the rule allows, the lock settles and never moves back. The second keeps the
first honest: upgrades do happen in that model. The third shows what the rule
prevents: without it, TLC finds a history where a plugin’s build goes 1, 2, 1
and a teammate’s upgrade moves the lock back.
A specification only says what the design does. To tie it to the CLI, a journey
records the lock after each real reflow init --upgrade and checks the recording
with tla.trace, as above.
Limits
Section titled “Limits”- TLC checks the model its configuration bounds, not the system: a pass says nothing about larger constants. A check is only as good as the specification.
- Time and memory grow steeply with constants. Raise
heapMb,diskMbandtimeout=for a larger model, or make it smaller. - A specification is checked on a private copy: only the flow’s
.tlafiles and the configuration reach TLC, and nothing of your environment does. A specification that uses moduleJson, moduleIOUtilsor one of TLC’s own modules whose names start with an underscore is refused, because those modules read and write files on the machine; so is a flow file named like a module TLC ships. TLC still runs as you, with no operating-system sandbox. - TLC’s output and counterexamples are evidence your team can read, and the model’s constants and state values appear in them. Do not put secrets in a specification or a recording.
The bundled runtime and its licences
Section titled “The bundled runtime and its licences”The plugin carries two things besides its own program:
- TLC 1.8.0,
tla2tools.jar, built from the tlaplus/tlaplus source at commitbc1b506bdcad80bb518bf3776a9161c34ff0fc4c(the v1.8.0 release) with the same contents as that release’s jar. The TLA+ tools are MIT-licensed. The jar also bundles Apache Commons Math, Gson, prettier4j and Apache Geronimo Activation (Apache-2.0), JLine (BSD-3-Clause), Eclipse LSP4J (EPL-2.0 or BSD-3-Clause) and Jakarta Mail (EPL-2.0 with the GPL-2.0 Classpath Exception as secondary licence). - A Java runtime made with
jlinkfrom Eclipse Temurin 21 (jdk-21.0.13+9), holding only the Java modules TLC uses. It is GPL-2.0 with the Classpath Exception; its source is the adoptium/jdk21u repository at that tag.
The installed plugin keeps every licence and notice in notices/ and
tlc/jre/legal/, with the source location of each.