tla-spec

name	tla-spec
description	Use when writing or reviewing TLA+ specifications for coordination protocols, when verifying safety/liveness properties of distributed algorithms, or when TLC model checking fails and you need diagnostic guidance. Evidence-backed TLA+ correctness methodology.
user-invocable	true

TLA+ Specification Correctness Guide

A phased methodology for writing correct TLA+ specifications. Every rule, pattern, and recommendation traces to established literature, Lamport's own specifications, or battle-tested industrial practice. No guessing.

This skill guides you through specification from foundations to model checking configuration. Follow the phases in order for new specs; jump to specific phases for targeted reviews.

Evidence Base

ID	Source	Key Principle
M1	Lamport, Specifying Systems (2002)	Canonical form: Init /\ [][Next]_vars /\ Fairness
M2	Lamport, Specifying Systems Ch. 6	Stuttering: [][Next]_vars permits stuttering steps; compositional refinement
M3	Lamport, Specifying Systems Ch. 8	Liveness: temporal properties, fairness as specification component
M4	Lamport, The Temporal Logic of Actions (1994)	Weak vs strong fairness definitions and selection criteria
M5	Lamport, Specifying Systems Ch. 5	UNCHANGED: every action must specify all unmodified variables
M8	Lamport, Specifying Systems Ch. 2-4	Abstraction: model WHAT not HOW, separate interface from implementation
M9	Lamport, TLA+ community practice	TypeOK as first invariant constraining variable domains
M10	Newcombe et al., CACM 2015	AWS experience: 3-5 processes sufficient for most design bugs
M11	TLC reference manual	TLC config options and their soundness guarantees
M12	Yu et al., Model Checking TLA+ Specifications (1999)	TLC implementation, symmetry reduction, state constraints
M14	Lamport, Specifying Systems; Raft TLA+ spec	Distributed systems patterns in TLA+
M16	Lamport, A PlusCal User's Manual (2009)	PlusCal as algorithmic specification language compiling to TLA+

Confidence Tiers

Every rule is tagged with a confidence tier. Higher tiers have stronger evidence and should be followed more strictly.

Tier	Meaning	Compliance
T1	High confidence, strong evidence from multiple sources	Non-negotiable for correctness
T2	Good evidence, note caveats	Strong default, deviate with documented reason
T3	Use with caution, limited evidence	Useful guidance, verify in your context

When to Use

• Writing a new TLA+ specification for any protocol or algorithm
• Reviewing an existing TLA+ specification for correctness
• Adding liveness properties to a safety-only specification
• Configuring TLC for model checking
• Modeling distributed systems protocols (consensus, replication, leader election)
• Deciding between PlusCal and TLA+ for a new specification

When NOT to Use

• Writing implementation code (this is about specifications, not programs)
• Working with other formal methods (Alloy, SPIN, Coq) — different tools, different rules
• Simple sequential algorithms where testing suffices
• When you need a TLA+ syntax tutorial (this assumes basic TLA+ literacy)

---

Phase 1: Specification Foundations

Establish the structural skeleton of a correct specification. Every TLA+ specification must satisfy these non-negotiable fundamentals before any properties are checked.

1.1 Canonical Form [T1, M1, P4.1.F1]

Use the canonical form as the default template for all specifications.

Safety-only specification (no liveness requirements):

---- MODULE MyProtocol ----
EXTENDS Integers, Sequences, FiniteSets, TLC

CONSTANTS
    Node,       \* Set of participating nodes
    MaxValue    \* Domain bound for model checking

VARIABLES
    state,      \* Per-node local state
    msgs        \* Set of in-flight messages (or Bag for realism)

vars == <<state, msgs>>

------------------------------------------------------------
\* Type invariant — ALWAYS define first [T1, M9]
TypeOK ==
    /\ state \in [Node -> {"idle", "active", "done"}]
    /\ msgs \subseteq MessageType

------------------------------------------------------------
\* Initial state
Init ==
    /\ state = [n \in Node |-> "idle"]
    /\ msgs = {}

------------------------------------------------------------
\* Actions — each MUST specify UNCHANGED for all unmodified variables [T1, M5]
ActionA(n) ==
    /\ state[n] = "idle"
    /\ state' = [state EXCEPT ![n] = "active"]
    /\ UNCHANGED <<msgs>>

ActionB(n) ==
    /\ state[n] = "active"
    /\ msgs' = msgs \cup {[type |-> "done", from |-> n]}
    /\ UNCHANGED <<state>>

------------------------------------------------------------
\* Next-state relation
Next ==
    \E n \in Node :
        \/ ActionA(n)
        \/ ActionB(n)

------------------------------------------------------------
\* Specification — canonical form
Spec == Init /\ [][Next]_vars

====

Safety + liveness specification (add fairness only when needed):

\* Add ONLY for liveness properties [T1, M1, M3]
Fairness ==
    /\ \A n \in Node : WF_vars(ActionA(n))
    /\ \A n \in Node : WF_vars(ActionB(n))

Spec == Init /\ [][Next]_vars /\ Fairness

Caveat [P4.1.F1]: Canonical form is a default template, not a law. Lamport himself deviates in some specifications (e.g., omitting fairness entirely for safety-only specs, using different temporal formulas for specific refinement mappings). If you deviate, document WHY with a reference to the specific pattern you are following.

1.2 Stuttering Invariance Checklist [T1, M2, M5]

Stuttering steps (where no variable changes) are fundamental to TLA+ and enable compositional refinement. The [][Next]_vars form explicitly permits them — this is not optional.

STUTTERING CHECKLIST
────────────────────
[ ] Specification uses [][Next]_vars (NOT [][Next])
    → [][Next] without _vars FORBIDS stuttering and breaks refinement.
    → The ONLY valid form is [][Next]_vars where vars is the
      tuple of ALL specification variables.

[ ] vars tuple contains ALL declared VARIABLES
    → If you add a variable, update the vars tuple immediately.
    → Missing a variable from vars silently permits arbitrary changes to it.

[ ] Every action specifies UNCHANGED for ALL unmodified variables
    → An action that mentions v1' but not v2' leaves v2 unconstrained.
    → TLC will explore states where v2 takes ANY value in its type domain.
    → This is the #1 source of spurious counterexamples.

Variable grouping pattern for specs with many variables:

\* Group related variables for manageable UNCHANGED clauses
nodeVars    == <<state, epoch>>
networkVars == <<msgs, delivered>>
configVars  == <<members, leader>>

vars == <<nodeVars, networkVars, configVars>>

\* Actions use group UNCHANGED
SendMessage(n) ==
    /\ ...
    /\ msgs' = msgs \cup {msg}
    /\ UNCHANGED <<nodeVars, configVars, delivered>>

1.3 TypeOK as First Invariant [T1, M9]

TypeOK constrains the domains of all variables. It is always the first invariant you write and the first invariant you check.

Why TypeOK matters:

• Catches variable domain errors before expensive property checking
• Acts as a sanity check that Init and Next are well-formed
• Provides a foundation for TLAPS proofs (type correctness is a proof obligation)
• Rapidly detects missing UNCHANGED clauses (unconstrained variables violate TypeOK)

TypeOK construction rules:

TYPEOK CONSTRUCTION
───────────────────
[ ] Every VARIABLE appears in TypeOK

[ ] TypeOK constrains variables to finite domains for TLC
    → "x \in Nat" is valid TLA+ but NOT model-checkable
    → Use "x \in 0..MaxBound" for model checking

[ ] TypeOK is checked BEFORE other invariants
    → In the TLC config: INVARIANT TypeOK, SafetyProp1, SafetyProp2
    → TypeOK violations are always the first thing to debug

[ ] Function-valued variables use domain constraints
    → state \in [Node -> StatusSet] not just "state is a function"
    → Check both the domain AND the range

TypeOK patterns by variable type:

Variable Type	TypeOK Pattern	Example
Simple value	v \in DomainSet	epoch \in Nat (or 0..MaxEpoch for TLC)
Function	v \in [Domain -> Range]	state \in [Node -> {"idle","active"}]
Set	v \subseteq BaseSet	msgs \subseteq MessageType
Sequence	v \in Seq(ElemType)	log \in Seq(Entry) (use BSeq(Entry, MaxLen) for TLC)
Record	v \in [field1: T1, field2: T2]	msg \in [type: MsgTypes, from: Node]
Optional	v \in T \cup {None}	leader \in Node \cup {None}
Bag/Multiset	Custom predicate	BagToSet(msgs) \subseteq MessageType

---

Phase 2: Abstraction and Modeling

Select the right level of abstraction BEFORE writing specification logic. Wrong abstraction is the most expensive specification error — it wastes model-checking time on irrelevant detail or misses real bugs by over-abstracting.

2.1 Seven-Step Abstraction Framework [T2, P3.1, M8]

Follow these steps in order when starting a new specification.

Step 1: State the property first

Before modeling any behavior, write down the property you want to verify in plain English. This determines what MUST be in the specification and what can be abstracted away.

Example:
  Property: "No two nodes hold the lock simultaneously"
  → Need: lock state per node
  → Don't need: network packet format, serialization, retry timers

Step 2: Identify minimal state

List the minimum set of variables needed to express the property from Step 1. Every variable must appear in at least one property or be necessary for computing a variable that does.

Minimal state test: For each variable, ask:
  "If I remove this variable, can I still express all my properties?"
  If yes → remove it.

Step 3: Model the environment as nondeterminism

Do not model external systems (clients, networks, OS) in detail. Replace them with nondeterministic choices that capture all possible behaviors.

\* BAD: modeling a specific client
ClientSend == /\ clientState = "ready"
              /\ clientState' = "waiting"
              /\ ...

\* GOOD: nondeterministic environment
ReceiveRequest(n) == \* A request can arrive at any node, any time
    /\ state[n] = "idle"
    /\ state' = [state EXCEPT ![n] = "processing"]
    /\ UNCHANGED <<...>>

Step 4: Choose communication model

Model	TLA+ Representation	Use When	Tradeoff
Set of messages	msgs \subseteq MsgType	Safety properties only	Simplest; loses ordering and duplicates
Bag (multiset)	msgs \in BagType	Need duplicate detection	Realistic; moderate complexity
Sequence per link	chan \in [Link -> Seq(MsgType)]	FIFO ordering required	Most complex; needed for TCP-like channels

[T2, P3.4, M14]: For most distributed protocol specifications, start with a set model. Upgrade to bag/sequence only if a property depends on message ordering or duplicate counting.

Step 5: Separate WHAT from HOW

Specify the intended behavior, not the implementation mechanism.

\* BAD: specifying HOW (implementation detail)
AcquireLock(n) ==
    /\ Send([type |-> "lock_req", from |-> n])
    /\ WaitForReply(n)
    /\ ProcessReply(n)

\* GOOD: specifying WHAT (observable behavior)
AcquireLock(n) ==
    /\ lock = None
    /\ lock' = n
    /\ UNCHANGED <<...>>

Step 6: Diagnose over/under-specification

Symptom	Diagnosis	Fix
TLC explores billions of states for a 3-node model	Over-specified (too much detail)	Remove implementation-level state
Safety property passes but system is clearly wrong	Under-specified (missing behaviors)	Add actions for failure cases, concurrent operations
Liveness property fails with trivial counterexample	Missing fairness or missing actions	Check that all intended behaviors have actions
No errors but the spec "feels wrong"	Wrong abstraction level	Return to Step 1, re-examine the property

Step 7: Refine incrementally

Start with the simplest correct spec and add detail only when needed to express properties that the simpler spec cannot. Each refinement step should be verifiable: the refined spec should refine (implement) the abstract spec.

2.2 Ten Distributed Systems Patterns [T2, P3.4, M14]

Common modeling patterns for distributed protocols. Each pattern includes the TLA+ idiom and notes on when to use it.

Pattern 1: Quorum

\* Abstract: CONSTANT set of quorums
CONSTANT Quorum
ASSUME QuorumAssumption ==
    /\ \A Q \in Quorum : Q \subseteq Node
    /\ \A Q1, Q2 \in Quorum : Q1 \cap Q2 /= {}

\* OR computed majority (simpler for symmetric systems)
Quorum == {S \in SUBSET Node : Cardinality(S) * 2 > Cardinality(Node)}

For model checking, the computed form is often better (no need to enumerate quorums in the config). For proof, the abstract CONSTANT form is more general.

Pattern 2: Epoch / Term (Monotonic Counter)

\* Per-node monotonic epoch
VARIABLE currentEpoch  \* currentEpoch \in [Node -> Nat]

\* Epoch advances are strictly increasing per node
AdvanceEpoch(n) ==
    /\ currentEpoch' = [currentEpoch EXCEPT ![n] = currentEpoch[n] + 1]
    /\ ...

\* Stale-epoch rejection
ProcessMessage(n, msg) ==
    /\ msg.epoch >= currentEpoch[n]  \* reject stale
    /\ ...

Pattern 3: Leader Election (Nondeterministic)

\* Abstract leader election — nondeterministic candidacy
BecomeLeader(n) ==
    /\ \A m \in Node : leader[m] /= n  \* not already leader
    /\ leader' = [leader EXCEPT ![n] = n]
    /\ currentEpoch' = [currentEpoch EXCEPT ![n] = currentEpoch[n] + 1]
    /\ UNCHANGED <<...>>

Do NOT model the election protocol (Raft, ZAB) unless you are verifying the election protocol itself. Abstract it as nondeterministic leader selection with appropriate constraints.

Pattern 4: Timeout (Always-Enabled Action, NO Clock)

\* BAD: modeling a clock for timeouts
Timeout(n) ==
    /\ clock[n] >= deadline[n]  \* NO — do not model clocks
    /\ ...

\* GOOD: timeout as an always-enabled action
Timeout(n) ==
    /\ state[n] = "waiting"
    /\ state' = [state EXCEPT ![n] = "timed_out"]
    /\ UNCHANGED <<...>>
\* Timeout can fire at ANY time a node is waiting — this captures
\* all possible timeout behaviors without modeling time.

[T1]: Never model real-time clocks in a TLA+ specification unless you are specifically verifying real-time properties. Timeouts are modeled as always-enabled actions that capture the nondeterminism of when they fire.

Pattern 5: Log Replication (Sequence with Truncate-Overwrite)

\* Log as sequence with append and truncate-overwrite
VARIABLE log  \* log \in [Node -> Seq(Entry)]

AppendEntry(n, entry) ==
    /\ log' = [log EXCEPT ![n] = Append(log[n], entry)]
    /\ UNCHANGED <<...>>

TruncateAndOverwrite(n, idx, entries) ==
    /\ log' = [log EXCEPT ![n] = SubSeq(log[n], 1, idx) \o entries]
    /\ UNCHANGED <<...>>

Pattern 6: Membership Change (Config as Log Entry)

\* Joint consensus: configuration transitions via log
VARIABLE config  \* config \in [Node -> SUBSET Node]

\* Configuration change is a special log entry
ProposeConfigChange(leader, newMembers) ==
    /\ AppendEntry(leader, [type |-> "config", members |-> newMembers])
    /\ config' = [config EXCEPT ![leader] = config[leader] \cup newMembers]
    /\ UNCHANGED <<...>>

Pattern 7: Idempotency (Accumulating Set)

\* Track processed operation IDs to ensure idempotency
VARIABLE processed  \* processed \in [Node -> SUBSET OpId]

ProcessOp(n, op) ==
    /\ op.id \notin processed[n]  \* skip if already processed
    /\ \* ... perform operation ...
    /\ processed' = [processed EXCEPT ![n] = processed[n] \cup {op.id}]
    /\ UNCHANGED <<...>>

Pattern 8: Two-Phase Protocol (Prepare-Collect-Decide)

\* Two-phase pattern: prepare → collect votes → decide
VARIABLE phase    \* [Node -> {"idle", "prepare", "decide"}]
VARIABLE votes    \* [Node -> SUBSET Node]

Prepare(n) ==
    /\ phase[n] = "idle"
    /\ phase' = [phase EXCEPT ![n] = "prepare"]
    /\ votes' = [votes EXCEPT ![n] = {}]
    /\ \* send prepare messages
    /\ UNCHANGED <<...>>

ReceiveVote(n, voter) ==
    /\ phase[n] = "prepare"
    /\ votes' = [votes EXCEPT ![n] = votes[n] \cup {voter}]
    /\ UNCHANGED <<...>>

Decide(n) ==
    /\ phase[n] = "prepare"
    /\ votes[n] \in Quorum  \* collected a quorum
    /\ phase' = [phase EXCEPT ![n] = "decide"]
    /\ UNCHANGED <<...>>

Pair with a refinement mapping to show this implements a simpler atomic specification. [T2]

Pattern 9: Failure and Restart (Durable vs Volatile State)

\* Failure: volatile state lost, durable state preserved
VARIABLE volatileState  \* lost on restart
VARIABLE durableState   \* preserved on restart

Crash(n) ==
    /\ volatileState' = [volatileState EXCEPT ![n] = InitVolatile]
    /\ UNCHANGED <<durableState, ...>>
    \* Durable state is UNCHANGED — this is the key invariant

Restart(n) ==
    /\ \* recover from durableState[n]
    /\ volatileState' = [volatileState EXCEPT
                           ![n] = RecoverFrom(durableState[n])]
    /\ UNCHANGED <<durableState, ...>>

Pattern 10: Ghost Variables (Append-Only History)

\* Ghost variable: records history for property checking
\* Does NOT affect system behavior — only used in invariants/properties
VARIABLE history  \* history \in Seq(Event)

\* Append to history in every action that is relevant
ActionWithHistory(n) ==
    /\ \* ... normal action logic ...
    /\ history' = Append(history, [type |-> "action", node |-> n, ...])
    /\ UNCHANGED <<...>>

\* Use ghost variable in properties
NoDoubleCommit ==
    \A i, j \in 1..Len(history) :
        /\ history[i].type = "commit"
        /\ history[j].type = "commit"
        /\ history[i].key = history[j].key
        => history[i].value = history[j].value

Ghost variables are specification-only artifacts. They are append-only (history never shrinks) and used solely to express properties that reference past states. Mark them clearly in comments.

---

Phase 3: Safety Verification

After establishing the specification structure (Phase 1) and modeling decisions (Phase 2), verify safety properties.

3.1 Safety Specification Checklist [T1, M9, M5]

SAFETY CHECKLIST
────────────────
[ ] TypeOK is defined and checked first
    → Every variable constrained to its domain [T1, M9]

[ ] All safety invariants expressed as state predicates
    → "P is always true" written as INVARIANT P in TLC config
    → For action properties, use [][ActionProp]_vars form

[ ] Deadlock-freedom checked between safety and liveness phases
    → TLC checks deadlock by default (all states have a Next step)
    → Intentional termination: add a Done action or use
      PROPERTY [][Next]_vars => <>[]done to distinguish
    → [P4.4.F6]: ALWAYS check deadlock-freedom after safety passes
      but BEFORE adding liveness. A deadlocked spec trivially
      satisfies some liveness properties (vacuous truth).

[ ] No CONSTRAINT in the TLC config for the final check
    → CONSTRAINT is acceptable during development to speed iteration
    → CONSTRAINT MUST be removed for the final safety verification
    → [T1, M11]: CONSTRAINT can hide states reachable via longer paths

[ ] Invariants are inductive (for TLAPS proofs)
    → An invariant I is inductive if: I /\ Next => I'
    → TypeOK is typically inductive; complex safety properties
      may need strengthening (adding auxiliary conjuncts)

3.2 Deadlock-Freedom Gate [T1, P4.4.F6]

This check is mandatory between the safety and liveness phases.

A specification deadlocks if some reachable state has no Next step enabled. TLC checks this by default. However:

1. If your protocol has intentional termination, you must distinguish it from unintentional deadlock:

\* Termination action — prevents false deadlock reports
Done ==
    /\ AllNodesFinished
    /\ UNCHANGED vars

Next == ActionA \/ ActionB \/ ... \/ Done

2. A deadlocked spec can vacuously satisfy liveness properties. If the system deadlocks in a state where the liveness property is already satisfied, TLC will report no error. This is not a real liveness guarantee.

DEADLOCK GATE
─────────────
[ ] TLC reports zero deadlock states
    OR
[ ] All "deadlock" states are intentional termination states
    AND they are documented in the spec
    AND a Done action is present

3.3 TLC Safety Configuration [T1, M11, M12]

Recommended TLC configuration for safety checking:

\* MyProtocol.cfg — safety checking configuration
SPECIFICATION Spec

\* Type invariant first, then safety properties
INVARIANT TypeOK
INVARIANT SafetyProperty1
INVARIANT SafetyProperty2

\* State constraint for development ONLY — remove for final check
\* CONSTRAINT StateConstraint

\* Symmetry sets — safe for safety properties [T1, M11]
SYMMETRY NodeSymmetry

\* Constants
CONSTANT Node = {n1, n2, n3}
CONSTANT MaxValue = 3

TLC Option	Safety Checking	Notes
INVARIANT	Sound	Always use for state predicates
CONSTRAINT	Sound but incomplete	May miss states reachable via longer paths; remove for final check
SYMMETRY	Sound if symmetry set is correct	Incorrect symmetry sets produce unsound results silently
VIEW	Sound	Reduces state space via abstraction
ACTION_CONSTRAINT	Sound	Restricts which actions TLC explores

---

Phase 4: Liveness Verification

Liveness properties ("something good eventually happens") require fairness assumptions and careful TLC configuration. This is where most soundness errors occur.

4.1 Six-Phase Liveness Methodology [T1, M3, P3.2, P3.3]

Follow these phases strictly in order.

Phase L1: Write safety first (complete Phase 3)

Never add liveness to a specification that has not passed safety checking. Liveness debugging on an incorrect safety spec is wasted effort.

Phase L2: Identify liveness requirements

Write down what MUST eventually happen in plain English:

Examples:
  - "Every request eventually receives a response"
  - "Every node eventually learns of every update"
  - "The leader eventually commits every proposed entry"
  - "The system eventually reaches a stable configuration"

Express each as a temporal formula:

\* "Every request eventually receives a response"
Liveness1 == \A r \in requests : <>(responded[r])

\* "The leader eventually commits" (conditional on leadership)
Liveness2 == []<>(committed = proposed)

\* Response: "always eventually" (repeated liveness)
Liveness3 == []<>(\E n \in Node : state[n] = "active")

Phase L3: Select fairness — WF first, SF only when needed [T2, M4, P3.3]

Use the fairness selection decision table:

Condition	Fairness	Rationale
Action is continuously enabled once enabled	WF_vars(Action)	WF suffices: if enabled forever, it eventually happens
Action is repeatedly enabled then disabled (intermittent)	SF_vars(Action)	SF needed: must happen if repeatedly enabled, even if intermittently disabled
Action represents environment/external input	No fairness	Never make the environment fair — it models adversarial behavior
Action is the composite Next	No fairness on Next alone	WF_vars(Next) says "some action happens" but does not guarantee WHICH action happens; useless for most properties
Timeout action	Usually no fairness	Timeouts model nondeterminism; fairness on timeouts constrains which timeouts fire

WF vs SF decision procedure:

1. Start with WF_vars(A) for every system action A
2. Check if TLC finds a liveness counterexample
3. If the counterexample shows Action A repeatedly enabled then disabled without executing, upgrade to SF_vars(A) for that specific action
4. Never start with SF — it is a stronger assumption and may hide real liveness bugs

[T2, M4]: Lamport's convention: "Weak fairness is almost always what you want." Strong fairness is needed only for actions that are intermittently disabled by other actions (e.g., a receive action that is enabled only when a message is in transit, and messages can be repeatedly consumed and re-sent).

Phase L4: Verify machine closure (automatic in canonical form)

A specification Spec == Init /\ [][Next]_vars /\ Fairness is machine-closed if the safety part (Init /\ [][Next]_vars) does not constrain which infinite behaviors are possible (only fairness does that).

In the canonical form, machine closure is guaranteed [T1, M1]. You only need to worry about machine closure if you deviate from canonical form (e.g., adding raw temporal formulas to the spec).

Phase L5: Model-check liveness [T1, P3.2, M11, M12]

THIS IS THE CRITICAL STEP. TLC's liveness checking has soundness traps that do not exist in safety checking.

LIVENESS MODEL-CHECKING RULES
──────────────────────────────
[ ] REMOVE all CONSTRAINT directives from the TLC config
    → CONSTRAINT + liveness = UNSOUND [T1, M11]
    → CONSTRAINT can hide infinite behaviors that violate liveness
    → This is NON-NEGOTIABLE for liveness checking

[ ] REMOVE all SYMMETRY directives from the TLC config
    → SYMMETRY + liveness = DANGEROUS [T1, M11]
    → Symmetry reduction may cause TLC to miss liveness violations
    → It is sometimes safe but the conditions are subtle;
      removing it is always safe

[ ] Use -lncheck final for production liveness verification
    → -lncheck final performs the complete liveness check
    → Without -lncheck, TLC may use an incomplete algorithm

[ ] Liveness properties go in PROPERTY (not INVARIANT)
    → INVARIANT is for state predicates (safety)
    → PROPERTY is for temporal formulas (liveness)

Phase L6: Debug liveness failures [T1, P3.2]

TLC liveness counterexamples have a lasso structure: a finite prefix followed by a back-loop to a previously visited state. The back-loop represents an infinite behavior where the liveness property is never satisfied.

Lasso structure:
  s0 → s1 → s2 → ... → sk → ... → sj
                               ↑        |
                               └────────┘
                             (back-loop: infinite repetition)

Debugging procedure:
1. Read the finite prefix: how does the system reach state sk?
2. Read the back-loop: what actions repeat forever?
3. Check: is there an action that SHOULD fire but doesn't?
   → If yes: add or strengthen fairness for that action
4. Check: is the counterexample realistic?
   → Unrealistic: the environment acts adversarially in a way your
     system need not tolerate. Consider if your liveness requirement
     is too strong.
   → Realistic: the protocol has a liveness bug. Fix the protocol.
5. Check: does the back-loop involve only stutter steps?
   → If yes: your specification may be missing an action.

4.2 Complete TLC Soundness Matrix [T1, M11, M12]

This is the complete map of TLC configuration options versus soundness for safety and liveness checking. Reference this table before every TLC run.

Config Option	Safety	Liveness	Risk	Recommendation
INVARIANT	Sound	N/A (wrong directive)	None for safety	Use for state predicates
PROPERTY	N/A (wrong directive)	Sound (with caveats below)	None	Use for temporal formulas
CONSTRAINT	Sound (but incomplete)	UNSOUND	High: hides reachable states from liveness check	Remove for final liveness check; acceptable during development for safety only
SYMMETRY	Sound (if correct)	Dangerous	Medium: may miss counterexamples	Remove for liveness; use only for safety with verified symmetry set
VIEW	Sound	Unverified	Medium: hash collisions possible	Use with caution; verify key results without VIEW
ACTION_CONSTRAINT	Sound	Context-dependent	Medium: may prevent actions needed for liveness counterexample	Review carefully for liveness
-lncheck final	N/A	Required for soundness	High if omitted: may use incomplete algorithm	Always use for production liveness checks
-workers N (N>1)	Sound	Sound (TLC 2.18+)	Low: older TLC versions had bugs with multi-worker liveness	Use current TLC version

[T1, P3.2]: The safe liveness workflow: (1) pass all safety checks with CONSTRAINT/SYMMETRY, (2) remove CONSTRAINT and SYMMETRY, (3) add PROPERTY directives, (4) run with -lncheck final, (5) accept the longer runtime.

---

Phase 5: Model Checking Configuration

5.1 Small Model Heuristics [T2, M10, P4.4.F3]

AWS's experience (Newcombe et al., CACM 2015): 3-5 processes are sufficient for finding most design bugs. Start small, increase only when needed.

Model Size	When Sufficient	When Insufficient
2 nodes	Mutual exclusion, simple leader-follower	Quorum-based protocols (need 3+)
3 nodes	Most consensus protocols, quorum systems	Protocols with f+1 requirements where f>1
4-5 nodes	Complex fault-tolerance (f=1 with 2f+1)	Threshold-dependent bugs (e.g., f=2 requires 5+ nodes)
>5 nodes	Byzantine fault tolerance (3f+1)	Rarely needed for design verification

Caveat [P4.4.F3]: Small models miss:

• Threshold-dependent bugs: Properties that only fail at specific quorum sizes (e.g., a bug that manifests only with exactly 2 of 5 nodes failing)
• Symmetry-breaking bugs: Bugs that require specific asymmetric configurations
• Scaling-related issues: Performance properties that degrade non-linearly

If your protocol has threshold-dependent behavior, test at least one configuration AT the threshold and one ABOVE it.

5.2 TLC Configuration Guide

Development configuration (fast iteration):

SPECIFICATION Spec
INVARIANT TypeOK
INVARIANT SafetyProperty
CONSTRAINT SmallStateConstraint   \* OK for safety development
SYMMETRY NodeSymmetry             \* OK for safety development
CONSTANT Node = {n1, n2, n3}     \* Start small

Final safety configuration (production):

SPECIFICATION Spec
INVARIANT TypeOK
INVARIANT SafetyProperty
\* NO CONSTRAINT — full state space
SYMMETRY NodeSymmetry             \* OK for safety (if correct)
CONSTANT Node = {n1, n2, n3}

Final liveness configuration (production):

SPECIFICATION Spec
INVARIANT TypeOK                  \* Keep safety checks active
PROPERTY LivenessProperty
\* NO CONSTRAINT — UNSOUND with liveness
\* NO SYMMETRY — DANGEROUS with liveness
CONSTANT Node = {n1, n2, n3}

TLC command-line flags:

Flag	Purpose	When to Use
-workers auto	Use all CPU cores	Always (production runs)
-lncheck final	Complete liveness check	Always for liveness verification
-deadlock	Disable deadlock checking	Only if spec has intentional terminal states AND Done action is present
-depth N	Limit search depth	Development only; never for final verification
-coverage N	Print coverage stats every N minutes	Development; helps find unreachable actions
-dump format file	Dump state graph	Debugging counterexamples
-simulate num=N	Random simulation instead of full BFS	Very large state spaces where exhaustive check is infeasible

5.3 Multi-Tool Awareness [T3, P4.3.F6, P4.4.F2]

TLC is not the only TLA+ verification tool. Be aware of alternatives and their strengths.

Tool	Technique	Strengths	Limitations
TLC	Explicit-state model checking	Complete for finite models; well-understood soundness; fast for small models	Exponential state explosion; finite models only
Apalache	Symbolic model checking (SMT)	Handles larger state spaces; bounded model checking for unbounded domains; type checking	Slower per-state; less mature than TLC; limited liveness support
TLAPS	Interactive theorem proving	Full mathematical proofs; unbounded verification; strongest guarantee	High manual effort; steep learning curve
Quint	Emerging: TLA+-like language with better tooling	Modern syntax; integrated testing; simulation	Not yet production-proven; subset of TLA+ expressiveness

TLC-specific advice is marked throughout this skill. Where behavior differs in Apalache, notes are included. However, this skill primarily targets TLC workflows. For Apalache-specific guidance, consult the Apalache documentation.

Apalache type annotations: Apalache requires type annotations that TLC ignores. If you plan to use both tools, add Apalache type annotations as comments:

\* @type: Set(NODE) => Bool;
IsQuorum(S) == Cardinality(S) * 2 > Cardinality(Node)

---

Phase 6: PlusCal Considerations [T3, M16, P4.4.F1]

PlusCal is a higher-level algorithmic language that compiles to TLA+. It is a valid choice for certain specifications.

6.1 PlusCal Decision Table

Factor	PlusCal	Raw TLA+
Author familiarity	Imperative/sequential programming	Set theory, temporal logic
Specification type	Sequential or simple concurrent algorithms	Complex concurrent/distributed protocols
Expressiveness ceiling	Limited: sequential composition, limited nondeterminism	Full: arbitrary temporal logic, flexible composition
Compilation	Compiles to TLA+ (can inspect/modify output)	Direct
Fairness	Automatic per-process fairness	Manual fairness specification
Best for	Teaching, prototyping, algorithm verification	Protocol verification, refinement, industrial use

[T3, P4.4.F1]: A finished PlusCal specification is better than an unfinished TLA+ specification. If PlusCal gets you to a checkable spec faster, use it. But know the ceiling: PlusCal cannot express all TLA+ patterns (e.g., arbitrary interleaving of non-process actions, complex fairness, stuttering-sensitive refinement).

When to switch from PlusCal to TLA+:

• You need fairness on individual actions (not just processes)
• You need to compose specifications via refinement
• You need ghost variables that participate in the temporal formula
• PlusCal's process model does not match your system's concurrency model

---

Quick Reference

Common mistakes catalog, specification template, decision tables, evidence traceability matrix, and references are in references/quick-reference.md.