loopeng-modelcheck

Model-check TLA+ specifications with TLC and validate check strength via mutation oracle.

Updated Jun 24, 2026
One-click install
npx skills add https://github.com/Hakkadaikon/hymme --skill loopeng-modelcheck-hakkadaikon
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: loopeng-modelcheck
Source: https://github.com/Hakkadaikon/hymme/tree/main/skills/loopeng-modelcheck
Command: npx skills add https://github.com/Hakkadaikon/hymme --skill loopeng-modelcheck-hakkadaikon

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? A TLA+ spec that passes TLC model checking may still be weak: its invariants might not actually distinguish buggy behavior. This Skill runs TLC model checking on a formalized design and then injects mechanical mutations into the spec itself to verify that the checks can catch injected faults, closing the gap between "no error found" and "the design is actually verified". ## Core Features & Use Cases - TLC Model Checking: Runs TLC against the Inv invariant over all reachable states of a <Name>.tla / <Name>.cfg pair produced by loopeng-formalize, surfacing counterexample traces when the design violates invariants. - Mutation Oracle: Injects mechanical mutations (e.g., < to \leq, = to #, /\ to \/) into the spec and confirms TLC kills each mutant, with procedures to distinguish true survivors (design holes) from equivalent mutants and to detect false-killed mutants where the mutation was never applied. - Use Case: After formalizing a queue protocol in TLA+, run the middle loop to confirm TLC reports no invariant violations, then verify every surviving mutant is an equivalent-mutant before declaring the design verified and handing off to Gherkin acceptance-spec generation. ## Quick Start Run the middle loop on my TLA+ spec by model-checking it with TLC and then applying the mutation oracle to check for surviving mutants.

Frequently Asked Questions about loopeng-modelcheck

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I model-check a TLA+ specification with TLC?

Run TLC against the module's .tla file together with its .cfg configuration, which defines the SPECIFICATION and INVARIANT to check. TLC explores all reachable states and reports either no error or a counterexample trace showing how the invariant was violated.

What is a mutation oracle for TLA+ specs?

A mutation oracle injects mechanical mutations into the spec, such as swapping operators, and checks whether TLC detects each mutant. A surviving mutant means the invariants cannot distinguish that bug, indicating the spec is too weak.

How do I tell equivalent mutants from real spec weaknesses?

Run TLC on the mutated version and compare the reachable state graph to the original. If distinct states and transitions are unchanged, the mutant is equivalent and unkillable; if the graph changes but TLC stays green, it is a true survivor revealing a design hole.

Why does TLC fail with NullPointerException tmpDir is null?

TLC and SANY die immediately when the JDK cannot create a tmp directory, common in sandboxes with read-only home caches. Set TMPDIR, create the directory, and pass -Djava.io.tmpdir via _JAVA_OPTIONS before invoking TLC.

When should I stop hunting surviving mutants?

Stop when true safety survivors reach zero, not when all mutants are killed. Regex-based oracles produce inherently unkillable equivalent mutants, so classify each remaining survivor, record the classification, and cut off once only equivalent classes remain.