{"id":24499196,"url":"https://github.com/will62794/spectacle","last_synced_at":"2025-08-10T22:42:18.519Z","repository":{"id":37998352,"uuid":"431608648","full_name":"will62794/spectacle","owner":"will62794","description":"Interactive, web-based tool for exploring, visualizing, and sharing formal specifications in TLA+.","archived":false,"fork":false,"pushed_at":"2025-08-03T02:46:22.000Z","size":30445,"stargazers_count":133,"open_issues_count":12,"forks_count":9,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-08-03T04:20:20.704Z","etag":null,"topics":["formal-methods","formal-specification","model-checking","tla","tlaplus","verification","visualization"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/will62794.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-11-24T19:43:28.000Z","updated_at":"2025-08-03T02:46:25.000Z","dependencies_parsed_at":"2024-04-15T06:20:44.709Z","dependency_job_id":"26449964-0fe7-4a54-bbe6-9a9798c04257","html_url":"https://github.com/will62794/spectacle","commit_stats":null,"previous_names":["will62794/spectacle","will62794/tla-web"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/will62794/spectacle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/will62794%2Fspectacle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/will62794%2Fspectacle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/will62794%2Fspectacle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/will62794%2Fspectacle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/will62794","download_url":"https://codeload.github.com/will62794/spectacle/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/will62794%2Fspectacle/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269799505,"owners_count":24477643,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["formal-methods","formal-specification","model-checking","tla","tlaplus","verification","visualization"],"created_at":"2025-01-21T22:13:29.481Z","updated_at":"2025-08-10T22:42:18.502Z","avatar_url":"https://github.com/will62794.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003c!-- # TLA\u003csup\u003e+\u003c/sup\u003e Web Explorer --\u003e\n# Spectacle \n\n\u003c!-- \u003cimg src=\"assets/glassestall3.png\" height=31 alt=\"Spectacle logo\" style=\"vertical-align: middle\"\u003e --\u003e\n\n\u003c!-- \u003cimg src=\"assets/glasses-svgrepo-com.svg\" width=\"50\" height=\"20\" alt=\"Spectacle logo\" style=\"vertical-align: middle\"\u003e --\u003e\n\n\nSpectacle is an interactive, web-based tool for exploring, visualizing, and sharing formal specifications written in the [TLA\u003csup\u003e+\u003c/sup\u003e specification language](https://lamport.azurewebsites.net/tla/tla.html).  The motivation is to have a better way to quickly interact with a formal specification and easily share results. For example, it provides a way to share protocol behaviors and counterexample traces in a convenient, portable, and repeatable manner. \n\nThe tool implements a [full TLA+ interpreter in Javascript](https://github.com/will62794/spectacle/blob/master/js/eval.js), building on top of the [TLA+ tree-sitter grammar](https://github.com/tlaplus-community/tree-sitter-tlaplus) for parsing specifications. This allows for interactive exploration of specs natively in the browser, without reliance on an external language server. A live version is hosted [here](https://will62794.github.io/spectacle/#!/home), and below are some example specifications to try out:\n\n- [Lock server](https://will62794.github.io/spectacle/#!/home?specpath=.%2Fspecs%2Flockserver.tla\u0026constants%5BServer%5D=%7B%22s1%22%2C%20%22s2%22%7D\u0026constants%5BClient%5D=%7B%22c1%22%2C%20%22c2%22%7D)\n- [Cabbage Goat Wolf Puzzle](https://will62794.github.io/spectacle/#!/home?specpath=.%2Fspecs%2FCabbageGoatWolf.tla) (animated)\n- [Distributed termination detection (EWD998)](https://will62794.github.io/spectacle/#!/home?specpath=.%2Fspecs%2FEWD998.tla\u0026constants%5BN%5D=3) (animated)\n- [Two phase commit](https://will62794.github.io/spectacle/#!/home?specpath=.%2Fspecs%2FTwoPhase_anim.tla\u0026constants%5BRM%5D=%7Brm1%2Crm2%2Crm3%7D) (animated)\n- [Paxos](https://will62794.github.io/spectacle/#!/home?specpath=.%2Fspecs%2FPaxos.tla\u0026constants%5BServer%5D=%7B%22s1%22%2C%22s2%22%2C%20%22s3%22%7D\u0026constants%5BSecondary%5D=%22Secondary%22\u0026constants%5BPrimary%5D=%22Primary%22\u0026constants%5BNil%5D=%22Nil%22\u0026constants%5BInitTerm%5D=0\u0026constants%5BAcceptor%5D=%7Ba1%2Ca2%2Ca3%7D\u0026constants%5BQuorum%5D=%7B%7Ba1%2Ca2%7D%2C%7Ba2%2Ca3%7D%2C%7Ba1%2Ca3%7D%2C%7Ba1%2Ca2%2Ca3%7D%7D\u0026constants%5BProposer%5D=%7Bp1%2Cp2%7D\u0026constants%5BValue%5D=%7Bv1%2Cv2%7D\u0026constants%5BBallot%5D=%7B0%2C1%2C2%2C3%7D\u0026constants%5BNone%5D=None)\n- [FlexiblePaxos](https://will62794.github.io/spectacle/#!/home?specpath=.%2Fspecs%2FFlexiblePaxos.tla\u0026constants%5BValue%5D=%7Bv1%2Cv2%7D\u0026constants%5BAcceptor%5D=%7Ba1%2Ca2%7D\u0026constants%5BQuorum1%5D=%7B%7Ba1%7D%2C%20%7Ba2%7D%7D\u0026constants%5BQuorum2%5D=%7B%7Ba1%2Ca2%7D%7D\u0026constants%5BBallot%5D=%7B0%2C1%2C2%2C3%7D)\n- [Raft](https://will62794.github.io/spectacle/#!/home?specpath=.%2Fspecs%2FAbstractRaft_anim.tla\u0026constants%5BServer%5D=%7Bs1%2Cs2%2C%20s3%7D\u0026constants%5BSecondary%5D=\"Secondary\"\u0026constants%5BPrimary%5D=\"Primary\"\u0026constants%5BNil%5D=\"Nil\"\u0026constants%5BInitTerm%5D=0) (animated)\n- [Snapshot Isolation](https://will62794.github.io/spectacle/#!/home?specpath=https%3A%2F%2Fraw.githubusercontent.com%2Fwill62794%2Fsnapshot-isolation-spec%2Frefs%2Fheads%2Fmaster%2FSnapshotIsolation.tla\u0026constants%5BtxnIds%5D=%7Bt0%2Ct1%2Ct2%7D\u0026constants%5Bkeys%5D=%7Bk1%2Ck2%7D\u0026constants%5Bvalues%5D=%7Bv1%2Cv2%7D\u0026constants%5BEmpty%5D=%22Empty%22) \n\nYou can also explore some interesting (and infamous) traces of different protocols:\n\n- [Solution to the cabbage goat wolf puzzle](https://will62794.github.io/spectacle/#!/home?specpath=.%2Fspecs%2FCabbageGoatWolf.tla\u0026trace=f3cb45ca%2C4357915f_7da698e2%2C126ae834_bf3b326e%2C76c2f092_652fccef%2C7229f089_f598e730%2C29e91cea_2ac3323e%2C50fe2821_bf3b326e%2C1d26e01c_9abe74ba%2C5f98d202_f598e730%2C3a9fa186_34b35f78%2Ca49994fc_bf3b326e%2Ceec0674a_652fccef%2C2afe63ed_f598e730%2C2883b61a_7da698e2%2C73ea1058_bf3b326e) (Cabbage Goat Wolf Puzzle)\n- [Raft log entry is written and later rolled back](https://will62794.github.io/spectacle/#!/home?specpath=.%2Fspecs%2FAbstractRaft_anim.tla\u0026constants%5BServer%5D=%7Bs1%2Cs2%2Cs3%7D\u0026constants%5BSecondary%5D=%22Secondary%22\u0026constants%5BPrimary%5D=%22Primary%22\u0026constants%5BNil%5D=%22Nil%22\u0026constants%5BInitTerm%5D=0\u0026trace=318c702a%2C0785f33f%2Cbbf1576c%2C79ad3285%2C708acdc2%2C2cd8de84%2Cfbeeee44%2Cac5d32a8%2Cc1e2949e%2Cd8547bce%2C7735c8df) (Raft)\n- [Write skew anomaly under snapshot isolation](https://will62794.github.io/spectacle/#!/home?specpath=https%3A%2F%2Fraw.githubusercontent.com%2Fwill62794%2Fsnapshot-isolation-spec%2Frefs%2Fheads%2Fmaster%2FSnapshotIsolation.tla\u0026constants%5BtxnIds%5D=%7Bt0%2Ct1%2Ct2%7D\u0026constants%5Bkeys%5D=%7Bk1%2Ck2%7D\u0026constants%5Bvalues%5D=%7Bv1%2Cv2%7D\u0026constants%5BEmpty%5D=%22Empty%22\u0026trace=4d9d875e%2Cb0868cc6%2C2f4fe314%2C351c185a%2C9af072f2%2C0ad7710e%2C39e3312d%2Cc5dbe6f2%2C0005740a) (Snapshot Isolation) \n- [Read-only anomaly under snapshot isolation](https://will62794.github.io/spectacle/#!/home?specpath=https%3A%2F%2Fraw.githubusercontent.com%2Fwill62794%2Fsnapshot-isolation-spec%2Frefs%2Fheads%2Fmaster%2FSnapshotIsolation.tla\u0026constants%5BtxnIds%5D=%7Bt0%2Ct1%2Ct2%7D\u0026constants%5Bkeys%5D=%7Bk1%2Ck2%7D\u0026constants%5Bvalues%5D=%7Bv1%2Cv2%7D\u0026constants%5BEmpty%5D=%22Empty%22\u0026trace=4d9d875e%2C27dfd06a%2C639eed1f%2C4cb5a71b%2C4708fef8%2C429a81d3%2Ce9311886%2C7478057a%2C2ea8cbe7%2C6a3128ec%2Cd2bef298%2C071ae0d9) (Snapshot Isolation)\n\n\n\n\u003c!-- The Javascript interpreter is likely slower than TLC, but highly efficient model checking isn't currently a goal of the tool.  --\u003e\n\n\u003c!-- Note also that you can basically use the existing web interface as a simple TLA+ expression evaluator, since making changes to definitions in the spec should automatically update the set of generated initial states. --\u003e\n\n\u003c!-- This project Utilizes the [TLA+ tree-sitter grammar](https://github.com/tlaplus-community/tree-sitter-tlaplus) to provide a web based TLA+ interface for exploring and sharing specifications.  --\u003e\n\u003c!-- There are still some TLA+ language features that [may not be implemented](https://github.com/will62794/spectacle/issues), but a reasonable number of specs should be handled correctly. For example, see this [Paxos spec](https://will62794.github.io/spectacle/#!/home?specpath=./specs/Paxos.tla). Additional testing is needed to verify the correctness of this interpreter on more complex specs. --\u003e\n\n\u003c!-- A basic, preliminary test suite can be found [here](https://will62794.github.io/spectacle/test.html). --\u003e\n\n## Usage Notes\n\nThe current tool expects that a specification has defined its initial state predicate and next state relation as `Init` and `Next` definitions, respectively. If your specification has these defined under different names, they will not be recognized and no initial state or next state evaluation will occur. In this case, you can still use the tool in REPL mode, though. \n\nEventually this will be made configurable, but the current tool looks for these hard-coded definitions. Also, there is incomplete support for user module imports, so specs are largely expected to be written in a single module. The interpreter does, however, support most operators from the [TLA+ standard modules](https://github.com/tlaplus/tlaplus/tree/c25a01393ef7d9b0315f3d3b1581988e7a4a57b2/tlatools/org.lamport.tlatools/src/tla2sany/StandardModules) by default.\n\nYou can also see a live demo of the tool and its features in [this presentation](https://www.youtube.com/watch?v=kSSWmxQLvmw), which also gives a very high level overview of the tool architecture and implementation details. \n\n### Running Locally\n\nIf you would like to run Spectacle locally and offline, you can do so by cloning the repo and running `make serve` from the root directory. This will start up a local Python server serving the app at [`127.0.0.1:8000`](http://127.0.0.1:8000).\n\n\u003c!-- Note that in addition to copying and pasting in the text of a TLA+ spec or writing it in the browser interface, you can also load a spec file from a given URL by using the following URL path format: --\u003e\n\u003c!-- ``` --\u003e\n\u003c!-- https://will62794.github.io/spectacle/#!/home?specpath=\u003ctla_spec_url\u003e --\u003e\n\u003c!-- ``` --\u003e\n\u003c!-- where `tla_spec_url` is a URL pointing to raw TLA+ module file. For example, you can see that [this link](https://will62794.github.io/tla-web/#!/home?specpath=https://gist.githubusercontent.com/will62794/4250c4b6a8e68b0d9e038186739af8cc/raw/3470b5999f896abb478733e8fc07e7ed9e3039da/HourClock.tla) loads a simple spec from a [personal Github gist](https://gist.githubusercontent.com/will62794/4250c4b6a8e68b0d9e038186739af8cc/raw/3470b5999f896abb478733e8fc07e7ed9e3039da/HourClock.tla). --\u003e\n\n\n\u003c!-- ### REPL Mode --\u003e\n\n\u003c!-- You can also open a specification in REPL mode, which gives you access to a live REPL for dynamically evaluating TLA+ expressions in the context of a specification. See [here](https://will62794.github.io/tla-web/#!/home?specpath=./specs/repl.tla\u0026repl=true) for an example REPL scratchpad. --\u003e\n\n## Testing\n\nCurrently, nearly all testing of the tool is done via conformance testing against TLC. That is, for a given specification, we [generate its reachable state graph using TLC](https://github.com/will62794/spectacle/blob/0060a9bedfbf78c9c6ef1eacf701b13f85048f5e/specs/with_state_graphs/gen_state_graphs.sh) and compare this for equivalence against the reachable state graph generated by the Javascript interpreter. You can see the result of all current tests that are run on [this page](https://will62794.github.io/spectacle/test.html), and the underlying test specs [here](https://github.com/will62794/spectacle/tree/0060a9bedfbf78c9c6ef1eacf701b13f85048f5e/specs/with_state_graphs).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwill62794%2Fspectacle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwill62794%2Fspectacle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwill62794%2Fspectacle/lists"}