Skip to content

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.

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:

Terminal window
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.

The binding takes no configuration:

{
"tla": {"provider": "TLA", "configuration": {}}
}
Terminal window
chmod 600 /absolute/path/to/bindings.json
reflow target --group design-checks --scope device --collection <collection-id> --bindings /absolute/path/to/bindings.json

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 design
providers:
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 Naturals
VARIABLE count
Init == count = 0
Next == count < 3 /\ count' = count + 1
Limit == count <= 3
====
```
```cfg file="Counter.cfg"
INIT Init
NEXT Next
INVARIANT Limit
CHECK_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.

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.

ArgumentMeaning
specThe module to check: a .tla file of the flow. Required.
configThe TLC configuration: a .cfg file of the flow. Default: spec with .cfg.
workersTLC worker threads, 1 to 64. Default 1.
heapMbJava heap in MiB, 64 to 65536. Default 1024.
diskMbLimit on TLC’s working files in MiB, 64 to 65536. Default 2048.
deadlockcheck (default) reports a state with no enabled action; ignore does not.
expectViolationThe step passes only when TLC violates exactly this invariant or property, or Deadlock.

What a step can end as:

OutcomeMeaning
holdsTLC explored every reachable state and found no violation.
violatedAn invariant, a property, an assertion or the deadlock check failed. The step keeps the counterexample.
spec errorTLC cannot parse or evaluate the specification or its configuration. The error names the file and line, for example PluginLock.tla:42:7.
refusedThe 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 verdictTLC 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.

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:

FileHolds
counterexample.txtThe counterexample as text: each step, its action and what changed.
counterexample.jsonEvery state in full, as TLC writes it with -dumpTrace json.
tlc-output.txtEverything TLC printed.
spec.tla, model.cfgThe 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 ever

Teammate 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.)

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:

KeyMeaning
stateRequired. The specification’s variables and their values after this line’s event.
eventOptional. The action of the specification this line is a step of. Without it, any step.
argsOptional. That action’s arguments, in order.
noteOptional. 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.

ArgumentMeaning
spec, configAs for tla.check. The configuration gives the constants, INIT and NEXT, and its invariants are checked on every matching state.
traceThe events: a .ndjson or .jsonl file of the flow, or step:NAME (below). Required.
init, nextThe initial predicate and next-state action, when the configuration names a SPECIFICATION instead.
stutteringrefuse (default) or allow: whether a line without an event may also be a step that changes nothing.
expectRejectionA line number: the step passes only when the recording is rejected at that line.
workers, heapMb, diskMbAs 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 → 1

expectRejection=4 passes only while the recording is rejected at line 4.

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.

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 return
providers:
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])]_vars
Stabilises == <>[]Quiet
====
```
```cfg file="PluginLock.guarded.cfg"
SPECIFICATION Spec
CONSTANTS
CatalogChoices <- GuardedCatalogs
Team <- TeamNewRule
INVARIANTS TypeOK AdviceCanBeFollowed
PROPERTIES Stabilises NeverMovesBack
CHECK_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.

  • 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, diskMb and timeout= for a larger model, or make it smaller.
  • A specification is checked on a private copy: only the flow’s .tla files and the configuration reach TLC, and nothing of your environment does. A specification that uses module Json, module IOUtils or 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 plugin carries two things besides its own program:

  • TLC 1.8.0, tla2tools.jar, built from the tlaplus/tlaplus source at commit bc1b506bdcad80bb518bf3776a9161c34ff0fc4c (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 jlink from 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.