tla-checker 0.9.0 → 0.24.8

package/README.md

@@ -1,71 +1,77 @@
-# tla-rs
+# WebAssembly
 
-A TLA+ model checker and interactive exploration tool written in Rust.
+The core library compiles to WASM for browser embedding. Every [GitHub release](https://github.com/fabracht/tla-rs/releases/latest) ships the built engine as `tla_checker.js` and `tla_checker_bg.wasm`, and publishes it to npm as [`tla-checker`](https://www.npmjs.com/package/tla-checker), with TypeScript declarations:
 
-tla-rs verifies TLA+ specifications by exploring all reachable states, checking invariants, and reporting counterexamples. Beyond pass/fail checking it offers an interactive TUI for stepping through state spaces, scenario-driven exploration, property-satisfaction analytics, parameter sweeps, tested demo walkthroughs (with an optional in-browser explorer), and an MCP server for agentic clients. The core library compiles to WebAssembly for browser embedding. It's a lightweight alternative to the official TLC model checker for specs that fit its supported subset.
+```bash
+npm install tla-checker
+```
+
+```js
+import init, { check_spec } from "tla-checker";
+await init();
+```
 
-## Installation
+To build it from a working copy (needs [cargo-make](https://github.com/sagiegurari/cargo-make) and the `wasm32-unknown-unknown` target; a `wasm-bindgen-cli` matching `Cargo.lock` is installed into `.wasm-tools/` when missing):
 
 ```bash
-cargo build --release
+cargo make wasm
 ```
 
-The binary will be at `target/release/tla`. Prebuilt binaries and the `tla-mcp` server are available via Homebrew, an install script, or GitHub releases — see the [MCP Server guide](MCP.md#install).
+This produces a `pkg/` directory with `tla_checker_bg.wasm`, the `tla_checker.js` bindings, and TypeScript declarations. The bindings are generated with `wasm-bindgen --target web`, so the module must be initialized before any binding is called: `await init()` (the default export, which fetches `tla_checker_bg.wasm` next to the JS file) or `initSync({ module: bytes })` with the wasm bytes.
 
-## Quick Start
+```js
+import init, { check_spec_with_options } from "./tla_checker.js";
+await init();
+```
 
-```bash
-tla spec.tla
-tla spec.tla -c 'N=5' -c 'Procs={"p1","p2","p3"}'
-tla spec.tla -c 'Proc={a,b,c}' --symmetry Proc
-tla spec.tla --config model.cfg
-tla spec.tla --quick    # limit to 10,000 states
-tla spec.tla -i         # interactive TUI
+The WASM API provides four checking bindings, each taking the spec source and returning a JSON string:
+
+| Binding | Arguments |
+|---------|-----------|
+| `check_spec(spec, constants_json)` | Default limits (1,000,000 states, depth 100). |
+| `check_spec_with_config(spec, constants_json, max_states, max_depth, allow_deadlock, export_dot)` | Explicit limits. |
+| `check_spec_with_cfg(spec, cfg_source, constants_json, max_states, max_depth, allow_deadlock, export_dot)` | A TLC-style cfg plus explicit limits. |
+| `check_spec_with_options(spec, options_json)` | A JSON options object (below). |
+
+The result has `success`, `error_type` and `error_message` (`null` on success), `states_explored`, `trace` (the counterexample as an array of strings, one formatted state each, or `null`), `dot` (the DOT graph when requested, or `null`), and `warnings`.
+
+The `check_spec_with_options` API accepts a JSON options object:
+
+```js
+const result = JSON.parse(check_spec_with_options(specSource, JSON.stringify({
+  constants: { N: 3 },
+  max_states: 10000,
+  max_depth: 50,
+  allow_deadlock: true,
+  export_dot: true,
+  dot_mode: "choices",   // "full", "trace", "clean" (default), "choices"
+  cfg_source: "INIT Init\nNEXT Next\n"
+})));
+
+if (result.dot) {
+  // DOT graph string: "digraph StateGraph { ... }"
+}
 ```
 
-Constants accept integers (`42`), booleans (`TRUE`), quoted strings (`"hello"`), sets (`{1,2,3}`), tuples (`<<1,2>>`), records (`[hp |-> 100]`), and functions (`a :> 1 @@ b :> 2`).
-
-A bare identifier is a **model value** — an uninterpreted, pairwise-distinct atom, matching TLC. `n1` is not equal to the string `"n1"`, so `-c 'Proc={a,b,c}'` yields three model values, not three strings. Symmetry reduction requires a set of model values (`--symmetry` rejects a set of quoted strings, as TLC does).
-
-## Options
-
-| Option | Description |
-|--------|-------------|
-| `-c NAME=VALUE` | Set a constant value |
-| `-s CONST` | Enable symmetry reduction for a constant |
-| `--config PATH` | Load TLC-style cfg file (auto-discovers `Spec.cfg` next to `Spec.tla`) |
-| `--max-states N` | Maximum states to explore (default: 1000000) |
-| `--max-depth N` | Maximum trace depth (default: 100) |
-| `-q` | Quick exploration (limit: 10,000 states) |
-| `--export-dot FILE` | Export state graph to DOT format |
-| `--dot-mode MODE` | DOT mode: `full`, `trace`, `clean` (default), `choices` |
-| `--allow-deadlock` | Allow states with no successors |
-| `--check-liveness` | Check liveness and fairness properties |
-| `--continue` | Continue past invariant violations |
-| `--count-satisfying NAME` | Count states satisfying a definition (repeatable) |
-| `--sweep NAME=V1;V2;...` | Sweep a constant across values, compare results |
-| `--scenario TEXT` | Explore a specific scenario (or `@file`) |
-| `-i` | Interactive TUI exploration mode |
-| `--present FILE` | Run a demo manifest (`.json`/`.toml`); TUI walkthrough, or `--validate` for a pass/fail report |
-| `--export-md FILE` | With `--present`: write a Markdown walkthrough |
-| `--export-html FILE` | With `--present`: write a self-contained HTML walkthrough |
-| `--explorable` | With `--export-html`: embed the wasm engine for in-browser state exploration |
-| `--json` | JSON output |
-| `-v` | Verbose output (depth breakdowns, etc.) |
-| `--version`, `-V` | Show version information |
-
-## Documentation
-
-| Guide | Contents |
-|-------|----------|
-| [CLI Guide](CLI_GUIDE.md) | Configuration files, scenarios, demo walkthroughs (incl. the `--explorable` browser explorer), interactive mode, analytics, output, and state-graph visualization |
-| [TLA+ Support](TLA_SUPPORT.md) | Supported operator subset, module instances, spec structure, and limitations |
-| [WebAssembly](WASM.md) | Browser-embeddable WASM API, including the live stepping bindings |
-| [MCP Server](MCP.md) | `tla-mcp` install, client registration, and tool reference |
-| [Syntax Status](SYNTAX_STATUS.md) | Operator-by-operator coverage table |
-| [Architecture](ARCHITECTURE.md) | Internal design |
-| [Practical TLA+ Guide](USER_GUIDE_TO_PRACTICAL_TLA.md) | Worked guidance for writing checkable specs |
-
-## License
-
-MIT
+| Option | Type | Description |
+|--------|------|-------------|
+| `constants` | object | Constant values (`{"N": 3, "Procs": ["a","b"]}`); a JSON array becomes a set, an object a record |
+| `cfg_source` | string | TLC-style cfg file contents |
+| `max_states` | number | Maximum states to explore |
+| `max_depth` | number | Maximum trace depth |
+| `allow_deadlock` | bool | Allow states with no successors |
+| `export_dot` | bool | Include DOT graph in result |
+| `dot_mode` | string | DOT export mode: `full`, `trace`, `clean` (default), `choices` |
+
+## Stepping API
+
+For step-by-step exploration there are four additional bindings. `explore_init`, `explore_next`, and `explore_invariants` power the [`--explorable` HTML export](https://github.com/fabracht/tla-rs/blob/main/CLI_GUIDE.md#demo-walkthroughs); `explore_eval` is available for embedders that want to evaluate an arbitrary expression at a state:
+
+| Binding | Returns |
+|---------|---------|
+| `explore_init(spec, cfg, constants)` | The initial states. |
+| `explore_next(spec, cfg, constants, state)` | The enabled transitions from a state, with action names and change deltas. |
+| `explore_eval(spec, cfg, constants, state, expr)` | The value of a TLA+ expression evaluated at a state. |
+| `explore_invariants(spec, cfg, constants, state)` | Each invariant's name and whether it holds at the state. |
+
+Each takes the spec source, a cfg source string (empty for none), and a JSON constants object; the per-state bindings also take a JSON state. All return a JSON string carrying an `ok` flag (and an `error` message when `ok` is false). States round-trip through the typed JSON form produced by `explore_init`/`explore_next`, so the result of one call can be fed straight into the next.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tla-checker",
-  "version": "0.9.0",
+  "version": "0.24.8",
   "type": "module",
   "description": "A TLA+ model checker compiled to WebAssembly",
   "license": "MIT OR Apache-2.0",
@@ -8,6 +8,10 @@
     "type": "git",
     "url": "git+https://github.com/fabracht/tla-rs.git"
   },
+  "homepage": "https://github.com/fabracht/tla-rs#readme",
+  "bugs": {
+    "url": "https://github.com/fabracht/tla-rs/issues"
+  },
   "main": "tla_checker.js",
   "types": "tla_checker.d.ts",
   "files": [
@@ -16,13 +20,5 @@
     "tla_checker.d.ts",
     "tla_checker_bg.wasm.d.ts"
   ],
-  "keywords": [
-    "tla",
-    "model-checking",
-    "formal-verification",
-    "wasm"
-  ],
-  "sideEffects": [
-    "./snippets/*"
-  ]
+  "keywords": ["tla", "model-checking", "formal-verification", "wasm"]
 }

package/tla_checker.js

@@ -242,7 +242,6 @@ export function explore_next(spec_source, cfg_source, constants_json, state_json
         wasm.__wbindgen_export3(deferred5_0, deferred5_1, 1);
     }
 }
-
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
@@ -262,8 +261,7 @@ function getDataViewMemory0() {
 }
 
 function getStringFromWasm0(ptr, len) {
-    ptr = ptr >>> 0;
-    return decodeText(ptr, len);
+    return decodeText(ptr >>> 0, len);
 }
 
 let cachedUint8ArrayMemory0 = null;
@@ -340,8 +338,9 @@ if (!('encodeInto' in cachedTextEncoder)) {
 
 let WASM_VECTOR_LEN = 0;
 
-let wasmModule, wasm;
+let wasmModule, wasmInstance, wasm;
 function __wbg_finalize_init(instance, module) {
+    wasmInstance = instance;
     wasm = instance.exports;
     wasmModule = module;
     cachedDataViewMemory0 = null;
@@ -351,11 +350,15 @@ function __wbg_finalize_init(instance, module) {
 
 async function __wbg_load(module, imports) {
     if (typeof Response === 'function' && module instanceof Response) {
+        if (!module.ok) {
+            throw new Error(`failed to fetch Wasm: ${module.status} ${module.statusText} fetching '${module.url}'`);
+        }
+
         if (typeof WebAssembly.instantiateStreaming === 'function') {
             try {
                 return await WebAssembly.instantiateStreaming(module, imports);
             } catch (e) {
-                const validResponse = module.ok && expectedResponseType(module.type);
+                const validResponse = expectedResponseType(module.type);
 
                 if (validResponse && module.headers.get('Content-Type') !== 'application/wasm') {
                     console.warn("`WebAssembly.instantiateStreaming` failed because your server does not serve Wasm with `application/wasm` MIME type. Falling back to `WebAssembly.instantiate` which is slower. Original error:\n", e);