tla-ts 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aiden Bai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,180 @@
-# Temporary Holding Version
+# tla-ts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![version](https://img.shields.io/npm/v/tla-ts?style=flat&colorA=000000&colorB=000000)](https://npmjs.com/package/tla-ts)
+[![downloads](https://img.shields.io/npm/dt/tla-ts.svg?style=flat&colorA=000000&colorB=000000)](https://npmjs.com/package/tla-ts)
+
+A TLA+ model checker in TypeScript, **2.4× faster than TLC**.
+
+tla-ts checks TLA+ specs with the same verdicts, error traces, and state counts as TLC. It runs in Node and in the browser without a JVM. Try it in the [playground](https://tla-ts.aidenybai.com).
+
+```ts
+import { check } from "tla-ts";
+
+const result = check({
+  source: `---- MODULE Counter ----
+EXTENDS Naturals
+VARIABLE x
+Init == x = 0
+Next == x' = x + 1
+Small == x < 3
+====`,
+  config: "INIT Init NEXT Next INVARIANT Small",
+});
+
+result.status; // "invariant-violation"
+```
+
+## Install
+
+```shell
+npm install tla-ts
+```
+
+## Usage
+
+```shell
+npx tla-ts Spec.tla
+npx tla-ts Spec.tla -config Other.cfg -deadlock
+npx tla-ts Spec.tla -workers auto
+```
+
+Without `-config`, tla-ts reads the `.cfg` file next to the spec. `-deadlock` turns off deadlock checking. `-workers` checks on several threads, one per core with `auto`. Output and exit codes follow TLC:
+
+| Exit code | Meaning                      |
+| --------: | ---------------------------- |
+|         0 | No error found               |
+|        10 | An assumption is false       |
+|        11 | Deadlock                     |
+|        12 | Invariant or property broken |
+|        13 | Liveness violation           |
+
+## API reference
+
+### `check`
+
+Checks a spec against a TLC configuration and returns the result. It explores every reachable state breadth-first, as TLC does.
+
+```ts
+import { check } from "tla-ts";
+
+const result = check({
+  source: specSource,
+  config: configSource,
+  loadModule: (name) => modules[name],
+  onPrint: (text) => console.log(text),
+});
+```
+
+Options:
+
+- `source`: the TLA+ module to check
+- `config`: a TLC configuration, as source text or as the result of `parseConfig`
+- `loadModule`: maps a module name to its source, for modules other than the standard modules
+- `onPrint`: receives the output of `Print` and `PrintT`, which defaults to `console.log`
+- `readFile` and `writeFile`: let the Json module read and write files. Without them, it has no file access
+
+The result has `status`, `violation`, `generatedStates`, `distinctStates`, and `depth`. `status` is `"success"`, `"assumption-violation"`, `"invariant-violation"`, `"property-violation"`, `"liveness-violation"`, or `"deadlock"`. `violation` holds the name of what failed and the trace that reaches it. For a liveness violation, `violation.loopStart` is the trace index where the lasso loops back.
+
+`check` supports:
+
+- **Standard modules**: Naturals, Integers, Sequences, FiniteSets, TLC, Bags, Reals, RealTime, Toolbox, and the community modules TLCExt, Json, and Randomization
+- **Modules**: `EXTENDS`, nested modules, and `INSTANCE` with `WITH` substitutions, `LAMBDA` substitutions for operator parameters, named instances, parameterized instances, and instances inside `LET`
+- **Configuration**: `INIT`, `NEXT`, `SPECIFICATION`, `CONSTANTS`, `INVARIANTS`, `PROPERTIES`, `CONSTRAINTS`, `ACTION_CONSTRAINTS`, `SYMMETRY`, `VIEW`, `POSTCONDITION`, `CHECK_DEADLOCK`, and `_POSSIBLE` properties
+- **Properties**: invariants, `[][A]_v`, and every temporal formula TLC accepts, checked through TLC's tableau construction under the fairness and temporal conjuncts of the specification
+- **Subexpression references**: selectors such as `F(2)!3`, `Op!<<`, `Op!>>`, `Op!:`, `Op!@`, and `Op!(x)`, labels such as `Op!lab`, and names of `THEOREM` formulas
+- **TLC semantics**: 32-bit integer overflow errors, `ENABLED`, `TLCGet` and `TLCSet` with TLC's counters and registers, and TLC's enumeration order for `CHOOSE` and quantifiers
+
+### `checkInParallel`
+
+Checks a spec on several worker threads and resolves to the same result as `check`. It takes the options of `check` plus `workers`, and runs in Node, Bun, Deno, and the browser.
+
+```ts
+import { checkInParallel } from "tla-ts";
+
+const result = await checkInParallel({ source: specSource, config: configSource, workers: 4 });
+```
+
+Workers deduplicate states by 64-bit fingerprint, as TLC does. When a run finds a violation, or the spec uses liveness properties or impure operators such as `Print`, `checkInParallel` falls back to `check` and returns its exact result and trace.
+
+### `parseModule`
+
+Parses a TLA+ module into its syntax tree. Throws `TlaSyntaxError` on invalid input.
+
+```ts
+import { parseModule } from "tla-ts";
+
+const module = parseModule(specSource);
+module.name; // "Counter"
+```
+
+### `parseConfig`
+
+Parses a TLC configuration file into a `ModelConfig`. Pass the result to `check` to change it before checking.
+
+```ts
+import { check, parseConfig } from "tla-ts";
+
+const config = parseConfig(configSource);
+config.checkDeadlock = false;
+check({ source: specSource, config });
+```
+
+### `formatValue`
+
+Prints a value in TLA+ syntax, as TLC prints it in traces.
+
+```ts
+import { formatValue } from "tla-ts";
+
+result.violation?.trace.forEach((step) => {
+  Object.entries(step.state).forEach(([name, value]) => console.log(name, formatValue(value)));
+});
+```
+
+### Errors
+
+Every error extends `TlaError`:
+
+- `TlaSyntaxError`: the module does not parse
+- `TlaConfigError`: the configuration is invalid or refers to an unknown name
+- `TlaEvaluationError`: evaluation failed, as when TLC reports an error
+- `TlaUnsupportedError`: the spec uses a feature tla-ts does not support yet
+
+## Benchmarks
+
+Wall time on one worker, including JVM and Node startup. Both checkers report the same state counts on every model.
+
+| Spec                                                           | Distinct states |     TLC |  tla-ts | Speedup |
+| -------------------------------------------------------------- | --------------: | ------: | ------: | ------: |
+| [Two-phase commit](packages/tla-ts/benchmarks/commit)          |         282,251 |  4.32 s |  2.01 s |    2.2× |
+| [Dining philosophers](packages/tla-ts/benchmarks/philosophers) |         128,889 |  1.06 s |  0.71 s |    1.5× |
+| [Bounded queue](packages/tla-ts/benchmarks/queue)              |          44,044 |  0.37 s |  0.17 s |    2.2× |
+| 542 conformance models                                         |                 | 986.6 s | 403.3 s |    2.4× |
+
+## Development
+
+```shell
+pnpm install
+pnpm test
+pnpm dev
+```
+
+`pnpm dev` starts the playground in `packages/website`.
+
+Run the conformance suite against TLC's recorded results:
+
+```shell
+pnpm --filter tla-ts conformance:fetch
+pnpm --filter tla-ts conformance
+```
+
+Rerun the benchmarks with `TLA2TOOLS_JAR` set to the path of `tla2tools.jar`:
+
+```shell
+pnpm --filter tla-ts bench
+pnpm --filter tla-ts bench:corpus
+```
+
+## License
+
+MIT

package/dist/cli.cjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * @license tla-ts
+ *
+ * Copyright (c) Aiden Bai
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+require("node:module").enableCompileCache?.(),Promise.resolve().then(()=>require("./run-cli.cjs")).then(e=>e.runCli());

package/dist/cli.d.cts

@@ -0,0 +1,9 @@
+/**
+ * @license tla-ts
+ *
+ * Copyright (c) Aiden Bai
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export {}

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @license tla-ts
+ *
+ * Copyright (c) Aiden Bai
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export {}

package/dist/cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * @license tla-ts
+ *
+ * Copyright (c) Aiden Bai
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import{enableCompileCache as e}from"node:module";e?.(),import(`./run-cli.js`).then(e=>e.runCli());

package/dist/index.cjs

@@ -0,0 +1,9 @@
+/**
+ * @license tla-ts
+ *
+ * Copyright (c) Aiden Bai
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./transfer.cjs"),t=require("./parallel.cjs");exports.TlaConfigError=e.v,exports.TlaError=e.y,exports.TlaEvaluationError=e.b,exports.TlaSyntaxError=e.x,exports.TlaUnsupportedError=e.S,exports.check=e.o,exports.checkInParallel=t.t,exports.formatValue=e.g,exports.parseConfig=e._,exports.parseModule=e.d;