tla-ts 0.0.1 → 0.0.2

package/README.md

@@ -3,14 +3,14 @@
 [![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**.
+A TLA+ model checker in TypeScript, **2× 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({
+const result = await check({
   source: `---- MODULE Counter ----
 EXTENDS Naturals
 VARIABLE x
@@ -33,31 +33,27 @@ 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
+npx tla-ts Spec.tla [-config Spec.cfg] [-deadlock] [-lncheck final] [-seed 0] [-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:
+- `-config`: the TLC configuration. Defaults to `Spec.cfg` next to the spec.
+- `-deadlock`: turns off deadlock checking.
+- `-lncheck final`: checks liveness once, after the search.
+- `-seed`: seeds `RandomElement` and the Randomization module. Defaults to 0.
+- `-workers`: the number of worker threads, or `auto` for one per core. Defaults to 1.
 
-| Exit code | Meaning                      |
-| --------: | ---------------------------- |
-|         0 | No error found               |
-|        10 | An assumption is false       |
-|        11 | Deadlock                     |
-|        12 | Invariant or property broken |
-|        13 | Liveness violation           |
+Output and exit codes match TLC's. The CLI loads a compiled Java class such as `Module.class` from the spec's directory as an override for that module.
 
 ## API reference
 
 ### `check`
 
-Checks a spec against a TLC configuration and returns the result. It explores every reachable state breadth-first, as TLC does.
+Checks a spec against a TLC configuration and resolves to the result.
 
 ```ts
 import { check } from "tla-ts";
 
-const result = check({
+const result = await check({
   source: specSource,
   config: configSource,
   loadModule: (name) => modules[name],
@@ -65,36 +61,33 @@ const result = check({
 });
 ```
 
-Options:
+| Option                  | Description                                                                              |
+| ----------------------- | ---------------------------------------------------------------------------------------- |
+| `source`                | The TLA+ module to check                                                                 |
+| `config`                | A TLC configuration, as text or as the result of `parseConfig`                           |
+| `loadModule`            | Returns the source of a module that isn't a standard module                              |
+| `loadClass`             | Returns a compiled Java class that overrides a module's operators with constants         |
+| `onPrint`               | Receives the output of `Print` and `PrintT`. Defaults to `console.log`                   |
+| `onPause`               | Runs when `TLCSet("pause", TRUE)` pauses checking, which resumes when it returns         |
+| `readFile`, `writeFile` | Read and write files for the Json module                                                 |
+| `seed`                  | A `bigint` seed. Defaults to `0n`, and matches TLC run with the same `-seed` and `-fp 0` |
+| `workers`               | The number of worker threads. Defaults to 1                                              |
 
-- `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 these fields:
 
-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.
+- `status`: `"success"`, `"deadlock"`, `"assumption-violation"`, `"invariant-violation"`, `"property-violation"`, `"liveness-violation"`, `"postcondition-violation"`, or `"error"`.
+- `violation`: the `name` of what failed and the `trace` that reaches it. `loopStart` marks where a liveness counterexample loops back.
+- `failure`: the message and trace when `status` is `"error"`.
+- `generatedStates`, `distinctStates`, and `depth`: TLC's state counts.
 
-`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.
+Workers run in Node, Bun, Deno, and the browser, and deduplicate states by 64-bit fingerprint as TLC does. `check` runs on the calling thread for specs with liveness properties or impure operators such as `Print`. After a violation, it reruns there to return the exact trace.
 
-```ts
-import { checkInParallel } from "tla-ts";
-
-const result = await checkInParallel({ source: specSource, config: configSource, workers: 4 });
-```
+`check` supports:
 
-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.
+- **Modules**: the standard modules, TLCExt, Json, and Randomization, plus `EXTENDS`, `INSTANCE`, and `LAMBDA`.
+- **Configuration**: `CONSTANTS`, `INIT`, `NEXT`, `SPECIFICATION`, invariants, properties, constraints, `SYMMETRY`, `VIEW`, `ALIAS`, `POSTCONDITION`, `CHECK_DEADLOCK`, and `_POSSIBLE`.
+- **Properties**: invariants and every temporal formula TLC accepts, checked through TLC's tableau construction.
+- **TLC semantics**: 32-bit integer overflow, `TLCGet` and `TLCSet`, subexpression references such as `Op!2`, and TLC's enumeration order for `CHOOSE` and quantifiers.
 
 ### `parseModule`
 
@@ -116,7 +109,7 @@ import { check, parseConfig } from "tla-ts";
 
 const config = parseConfig(configSource);
 config.checkDeadlock = false;
-check({ source: specSource, config });
+await check({ source: specSource, config });
 ```
 
 ### `formatValue`

package/dist/index.cjs

@@ -6,4 +6,4 @@
  * 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;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./transfer.cjs"),t=require("./parallel.cjs");exports.TlaConfigError=e.D,exports.TlaError=e.O,exports.TlaEvaluationError=e.k,exports.TlaSyntaxError=e.A,exports.TlaUnsupportedError=e.j,exports.check=t.t,exports.formatValue=e.S,exports.parseConfig=e.E,exports.parseModule=e._;

package/dist/index.d.cts

@@ -12,10 +12,22 @@ interface LocalResolution {
 interface SourceLocation {
   line: number;
   column: number;
+  range?: SourceRange;
+}
+interface SourceRange {
+  module: string;
+  start: SourceLocation;
+  end: SourceLocation;
 }
 interface NumberExpression {
   kind: "Number";
   value: number;
+  text?: string;
+  location: SourceLocation;
+}
+interface DecimalExpression {
+  kind: "Decimal";
+  text: string;
   location: SourceLocation;
 }
 interface StringExpression {
@@ -249,7 +261,7 @@ interface SubexpressionExpression {
   selectors: Selector[];
   location: SourceLocation;
 }
-type Expression = NumberExpression | StringExpression | IdentifierExpression | ApplyExpression | OperatorReferenceExpression | LambdaExpression | JunctionExpression | PrimeExpression | UnchangedExpression | EnabledExpression | IfExpression | CaseExpression | LetExpression | QuantifierExpression | UnboundedQuantifierExpression | ChooseExpression | SetEnumerationExpression | SetFilterExpression | SetMapExpression | TupleExpression | FunctionConstructionExpression | FunctionSetExpression | RecordExpression | ExceptExpression | ExceptAtExpression | FunctionApplicationExpression | FieldAccessExpression | ProductExpression | TemporalExpression | ActionExpression | FairnessExpression | LabelExpression | SubexpressionExpression;
+type Expression = NumberExpression | DecimalExpression | StringExpression | IdentifierExpression | ApplyExpression | OperatorReferenceExpression | LambdaExpression | JunctionExpression | PrimeExpression | UnchangedExpression | EnabledExpression | IfExpression | CaseExpression | LetExpression | QuantifierExpression | UnboundedQuantifierExpression | ChooseExpression | SetEnumerationExpression | SetFilterExpression | SetMapExpression | TupleExpression | FunctionConstructionExpression | FunctionSetExpression | RecordExpression | ExceptExpression | ExceptAtExpression | FunctionApplicationExpression | FieldAccessExpression | ProductExpression | TemporalExpression | ActionExpression | FairnessExpression | LabelExpression | SubexpressionExpression;
 interface OperatorParam {
   name: string;
   arity: number;
@@ -259,6 +271,7 @@ interface OperatorDefinition {
   name: string;
   params: OperatorParam[];
   body: Expression;
+  bodyRange?: SourceRange;
   isLocal: boolean;
   isRecursive: boolean;
   location: SourceLocation;
@@ -276,6 +289,7 @@ type Definition = OperatorDefinition | FunctionDefinition;
 interface Declaration {
   name: string;
   arity: number;
+  location: SourceLocation;
 }
 interface Assumption {
   name: string | undefined;
@@ -296,20 +310,101 @@ interface Instance {
   isLocal: boolean;
   location: SourceLocation;
 }
-interface OuterScope {
-  extends: string[];
-  symbols: Declaration[];
+interface NewSymbol {
+  kind: "NewSymbol";
+  name: string;
+  arity: number;
+  level: "Constant" | "Variable" | "State" | "Action" | "Temporal";
+  set: Expression | undefined;
+  location: SourceLocation;
+}
+interface AssumeProve {
+  kind: "AssumeProve";
+  assumptions: (Expression | NewSymbol | AssumeProve)[];
+  conclusion: Expression;
+  location: SourceLocation;
+}
+type Fact = Expression | {
+  kind: "ModuleFact";
+  name: string;
+  location: SourceLocation;
+};
+interface UseOrHide {
+  kind: "Use" | "Hide";
+  isOnly: boolean;
+  facts: Fact[];
+  defs: Fact[];
+  location: SourceLocation;
+}
+type Proof = {
+  kind: "Obvious" | "Omitted";
+  location: SourceLocation;
+} | {
+  kind: "By";
+  isOnly: boolean;
+  facts: Fact[];
+  defs: Fact[];
+  location: SourceLocation;
+} | {
+  kind: "Steps";
+  level: number;
+  steps: ProofStep[];
+  location: SourceLocation;
+};
+interface DefineStep {
+  kind: "Define";
+  definitions: (Definition | Instance)[];
+  location: SourceLocation;
+}
+type StepBody = UseOrHide | Instance | DefineStep | {
+  kind: "Have";
+  expression: Expression;
+} | {
+  kind: "Take";
+  names: string[];
+  bounds: Bound[];
+} | {
+  kind: "Witness";
+  expressions: Expression[];
+} | {
+  kind: "Pick";
+  names: string[];
+  bounds: Bound[];
+  body: Expression;
+} | {
+  kind: "Case";
+  expression: Expression;
+} | {
+  kind: "Assert";
+  isSuffices: boolean;
+  statement: Expression | AssumeProve;
+} | {
+  kind: "Qed";
+};
+interface ProofStep {
+  name: string | undefined;
+  body: StepBody;
+  proof: Proof | undefined;
+  location: SourceLocation;
+}
+interface Theorem {
+  name: string | undefined;
+  statement: Expression | AssumeProve;
+  proof: Proof | undefined;
+  location: SourceLocation;
 }
 interface Module {
   name: string;
-  outer: OuterScope | undefined;
   modules: Module[];
   extends: string[];
   constants: Declaration[];
-  variables: string[];
+  variables: Declaration[];
   definitions: Definition[];
   instances: Instance[];
   assumptions: Assumption[];
+  location: SourceLocation;
+  theorems: Theorem[];
+  uses: UseOrHide[];
 }
 type ConfigValue = {
   kind: "Number";
@@ -351,10 +446,28 @@ interface ModelConfig {
   checkDeadlock: boolean;
   symmetry: string | undefined;
   view: string | undefined;
+  alias: string | undefined;
   postconditions: string[];
   possible: string[];
+  periodic: string | undefined;
+  rlReward: string | undefined;
 }
 export declare const parseConfig: (source: string) => ModelConfig;
+export declare class TlaError extends Error {
+  constructor(message: string, cause?: unknown);
+}
+export declare class TlaSyntaxError extends TlaError {
+  constructor(message: string, cause?: unknown);
+}
+export declare class TlaConfigError extends TlaError {
+  constructor(message: string, cause?: unknown);
+}
+export declare class TlaEvaluationError extends TlaError {
+  constructor(message: string, cause?: unknown);
+}
+export declare class TlaUnsupportedError extends TlaError {
+  constructor(message: string, cause?: unknown);
+}
 interface ModelValue {
   kind: "ModelValue";
   name: string;
@@ -365,12 +478,17 @@ interface SetValue {
   hash: number;
   fingerprint: number;
 }
+interface MixedSetValue {
+  kind: "MixedSet";
+  elements: Value[];
+}
 interface FunctionValue {
   kind: "Function";
   domain: Value[];
   range: Value[];
   hash: number;
   fingerprint: number;
+  writtenKeys: Value[] | undefined;
 }
 interface IntervalValue {
   kind: "Interval";
@@ -414,58 +532,76 @@ interface FilteredSetValue {
   base: Value;
   test: (element: Value) => boolean;
 }
+interface UnionValue {
+  kind: "Union";
+  base: Value;
+}
+interface LazyFunctionParameter {
+  name: string;
+  domain: Value;
+}
+interface LazyFunctionSource {
+  parameters: LazyFunctionParameter[];
+  body: string;
+}
 interface LazyFunctionValue {
   kind: "LazyFunction";
   domain: Value;
   apply: (argument: Value) => Value;
+  source?: LazyFunctionSource;
 }
-type Value = boolean | number | string | ModelValue | SetValue | FunctionValue | IntervalValue | InfiniteSetValue | SubsetValue | FunctionSetValue | RecordSetValue | ProductSetValue | SequenceSetValue | SetOperationValue | FilteredSetValue | LazyFunctionValue;
-export declare const formatValue: (value: Value, isExpanded?: boolean) => string;
+type Value = boolean | number | string | ModelValue | SetValue | MixedSetValue | FunctionValue | IntervalValue | InfiniteSetValue | SubsetValue | FunctionSetValue | RecordSetValue | ProductSetValue | SequenceSetValue | SetOperationValue | FilteredSetValue | UnionValue | LazyFunctionValue;
+export declare const formatValue: (value: Value, isStrict?: boolean, isNormalized?: boolean) => string;
 interface CheckOptions {
   source: string;
   config: string | ModelConfig;
   loadModule?: (name: string) => string | undefined;
+  loadClass?: (name: string) => Uint8Array | undefined;
   onPrint?: (text: string) => void;
+  onPause?: () => void;
   readFile?: (path: string) => string | undefined;
   writeFile?: (path: string, content: string) => void;
+  seed?: bigint;
+  workers?: number;
+  livenessCheck?: "default" | "final";
 }
-type CheckStatus = "success" | "assumption-violation" | "invariant-violation" | "property-violation" | "liveness-violation" | "postcondition-violation" | "deadlock";
+type CheckStatus = "success" | "assumption-violation" | "invariant-violation" | "property-violation" | "liveness-violation" | "postcondition-violation" | "deadlock" | "error";
 interface TraceStep {
   action: string | undefined;
+  label: string | undefined;
   state: Record<string, Value>;
 }
 interface Violation {
   name: string;
   trace: TraceStep[];
   loopStart: number | undefined;
+  loopLabel?: string;
   message?: string;
+  counts?: string;
+  unwitnessed?: Postcondition;
+}
+interface Postcondition {
+  name: string;
+  message: string;
+  counts?: string;
+}
+interface EvaluationFailure {
+  message: string;
+  trace: TraceStep[];
+  initialState: Record<string, Value> | undefined;
+  exitCode: number;
 }
 interface CheckResult {
   status: CheckStatus;
   violation: Violation | undefined;
+  failure: EvaluationFailure | undefined;
   generatedStates: number;
   distinctStates: number;
+  queuedStates: number;
   depth: number;
+  outDegrees: number[] | undefined;
+  fingerprintDistance: bigint | undefined;
 }
-export declare const check: (options: CheckOptions) => CheckResult;
-export declare class TlaError extends Error {
-  constructor(message: string, cause?: unknown);
-}
-export declare class TlaSyntaxError extends TlaError {
-  constructor(message: string, cause?: unknown);
-}
-export declare class TlaConfigError extends TlaError {
-  constructor(message: string, cause?: unknown);
-}
-export declare class TlaEvaluationError extends TlaError {
-  constructor(message: string, cause?: unknown);
-}
-export declare class TlaUnsupportedError extends TlaError {
-  constructor(message: string, cause?: unknown);
-}
-interface ParallelCheckOptions extends CheckOptions {
-  workers: number;
-}
-export declare const checkInParallel: (options: ParallelCheckOptions) => Promise<CheckResult>;
+export declare const check: (options: CheckOptions) => Promise<CheckResult>;
 export declare const parseModule: (source: string) => Module;
-export type { CheckOptions, CheckResult, CheckStatus, ConfigValue, ConstantAssignment, ModelConfig, Module, ParallelCheckOptions, Substitution, TraceStep, Value, Violation };
+export type { CheckOptions, CheckResult, CheckStatus, ConfigValue, ConstantAssignment, EvaluationFailure, ModelConfig, Module, Substitution, TraceStep, Value, Violation };