tla-ts 0.0.1 → 0.0.3-dev.2032e26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/README.md +95 -40
  2. package/dist/index.cjs +1 -1
  3. package/dist/index.d.cts +216 -30
  4. package/dist/index.d.ts +216 -30
  5. package/dist/index.js +1 -1
  6. package/dist/parallel-worker.cjs +2 -2
  7. package/dist/parallel-worker.js +2 -2
  8. package/dist/parallel.cjs +1 -1
  9. package/dist/parallel.js +2 -2
  10. package/dist/run-cli.cjs +20 -1
  11. package/dist/run-cli.js +20 -1
  12. package/dist/transfer.cjs +392 -39
  13. package/dist/transfer.js +392 -39
  14. package/package.json +6 -2
  15. package/src/ast.ts +122 -5
  16. package/src/bags.ts +161 -71
  17. package/src/builtins.ts +203 -23
  18. package/src/bundled-modules.ts +63 -32
  19. package/src/check.ts +950 -238
  20. package/src/cli-options.ts +58 -0
  21. package/src/codegen.ts +52 -18
  22. package/src/config.ts +39 -11
  23. package/src/environment.ts +485 -140
  24. package/src/errors.ts +64 -1
  25. package/src/evaluate.ts +492 -138
  26. package/src/exit-codes.ts +75 -0
  27. package/src/fingerprints.ts +48 -13
  28. package/src/index.ts +9 -4
  29. package/src/instances.ts +221 -66
  30. package/src/java-overrides.ts +241 -0
  31. package/src/json.ts +153 -72
  32. package/src/levels.ts +850 -0
  33. package/src/lexer.ts +108 -29
  34. package/src/liveness.ts +47 -91
  35. package/src/obligation-action.ts +384 -0
  36. package/src/obligation-anon.ts +575 -0
  37. package/src/obligation-deref.ts +637 -0
  38. package/src/obligation-expression.ts +1060 -0
  39. package/src/obligation-format.ts +406 -0
  40. package/src/obligation-generate.ts +1074 -0
  41. package/src/obligation-levels.ts +329 -0
  42. package/src/obligation-module.ts +1042 -0
  43. package/src/obligation-printer.ts +889 -0
  44. package/src/obligation-proof.ts +76 -0
  45. package/src/obligation-source.ts +1084 -0
  46. package/src/obligation-tuples.ts +184 -0
  47. package/src/obligations.ts +316 -0
  48. package/src/parallel-worker.ts +186 -201
  49. package/src/parallel.ts +176 -84
  50. package/src/parser.ts +970 -206
  51. package/src/pretty-print.ts +259 -0
  52. package/src/randomization.ts +24 -113
  53. package/src/resolve.ts +472 -41
  54. package/src/run-cli.ts +427 -61
  55. package/src/runtime.ts +63 -28
  56. package/src/spec-description.ts +509 -0
  57. package/src/standard-levels.ts +105 -0
  58. package/src/standard-modules.ts +223 -92
  59. package/src/subexpressions.ts +21 -35
  60. package/src/substitution-levels.ts +184 -0
  61. package/src/successors.ts +266 -48
  62. package/src/symmetry.ts +79 -23
  63. package/src/tableau.ts +43 -37
  64. package/src/tlc-ext.ts +120 -33
  65. package/src/tlc-module.ts +71 -47
  66. package/src/tlc-modules.ts +1022 -0
  67. package/src/tlc-order.ts +511 -0
  68. package/src/tlc-random.ts +411 -0
  69. package/src/tlc-summary.ts +109 -0
  70. package/src/transfer.ts +26 -5
  71. package/src/values.ts +1234 -176
package/src/check.ts CHANGED
@@ -1,41 +1,85 @@
1
- import type { Assumption, Expression, SourceLocation } from "./ast";
2
- import { parseConfig, type ModelConfig } from "./config";
1
+ import type { Assumption, Definition, Expression, SourceLocation } from "./ast";
2
+ import { parseConfig, type ConfigValue, type ModelConfig } from "./config";
3
3
  import { getReadVariables } from "./dependencies";
4
4
  import { createEnvironment } from "./environment";
5
- import { TlaConfigError, TlaEvaluationError, TlaUnsupportedError } from "./errors";
6
5
  import {
6
+ getErrorExitCode,
7
+ TlaConfigError,
8
+ TlaEvaluationError,
9
+ TlaModuleError,
10
+ UNEXPECTED_EXCEPTION,
11
+ } from "./errors";
12
+ import { EXIT_STATUS, setExitCode, setNextStatePhase, withLivenessExitCode } from "./exit-codes";
13
+ import {
14
+ describeRange,
7
15
  evaluate,
8
16
  expectBoolean,
17
+ formatRange,
18
+ getChildren,
9
19
  getDefinition,
20
+ isConstantLevel,
21
+ isImpure,
22
+ isLocallyResolved,
10
23
  type Context,
11
24
  type Environment,
12
25
  type Scope,
13
26
  } from "./evaluate";
14
27
  import {
15
- ACTION_LEVEL,
16
28
  createLivenessChecker,
17
29
  expandTemporal,
18
30
  getLevel,
19
- TEMPORAL_LEVEL,
20
- toUnscopedExpression,
31
+ type Lasso,
21
32
  type LiveSuccessor,
22
33
  type ScopedExpression,
23
34
  type TemporalProperty,
24
35
  } from "./liveness";
25
- import { parseModule } from "./parser";
26
- import { getInitialStates, getSuccessors } from "./successors";
36
+ import { ACTION_LEVEL, createLevelAnalyzer, TEMPORAL_LEVEL } from "./levels";
37
+ import { prettyPrint } from "./pretty-print";
38
+ import {
39
+ forEachInitialState,
40
+ forEachSuccessor,
41
+ getInitialStates,
42
+ getSuccessors,
43
+ type Successor,
44
+ } from "./successors";
45
+ import {
46
+ getActionLabel,
47
+ getNextActions,
48
+ getSpecificationValue,
49
+ type SpecAction,
50
+ } from "./spec-description";
27
51
  import { getRepresentative, getSymmetryGroup } from "./symmetry";
52
+ import { getTlcStringOrder, getTlcVariableOrder } from "./tlc-order";
53
+ import { createTlcFingerprinter, getTlcFingerprint } from "./tlc-random";
28
54
  import { createCanonicalizer } from "./canonical";
29
55
  import { getPossibleCounts, type CheckerRuntime } from "./runtime";
30
- import { combineHash, formatValue, getValueHash, isSameValue, type Value } from "./values";
56
+ import { createCounterExample } from "./tlc-ext";
57
+ import { getFingerprintDistance, OUT_DEGREE_BUCKETS } from "./tlc-summary";
58
+ import {
59
+ combineHash,
60
+ formatValue,
61
+ getValueHash,
62
+ isFunctionValue,
63
+ isSameValue,
64
+ isUpdatedElementOf,
65
+ setStringOrder,
66
+ toFiniteFunction,
67
+ type Value,
68
+ } from "./values";
31
69
 
32
70
  export interface CheckOptions {
33
71
  source: string;
34
72
  config: string | ModelConfig;
35
73
  loadModule?: (name: string) => string | undefined;
74
+ loadClass?: (name: string) => Uint8Array | undefined;
36
75
  onPrint?: (text: string) => void;
76
+ onPause?: () => void;
37
77
  readFile?: (path: string) => string | undefined;
38
78
  writeFile?: (path: string, content: string) => void;
79
+ seed?: bigint;
80
+ workers?: number;
81
+ // TLC's -lncheck: "final" checks liveness only on the complete state graph.
82
+ livenessCheck?: "default" | "final";
39
83
  }
40
84
 
41
85
  export type CheckStatus =
@@ -45,10 +89,13 @@ export type CheckStatus =
45
89
  | "property-violation"
46
90
  | "liveness-violation"
47
91
  | "postcondition-violation"
48
- | "deadlock";
92
+ | "deadlock"
93
+ | "error";
49
94
 
50
95
  export interface TraceStep {
51
96
  action: string | undefined;
97
+ // TLC's name, parameters and location for the action that took this step.
98
+ label: string | undefined;
52
99
  state: Record<string, Value>;
53
100
  }
54
101
 
@@ -56,41 +103,75 @@ export interface Violation {
56
103
  name: string;
57
104
  trace: TraceStep[];
58
105
  loopStart: number | undefined;
106
+ loopLabel?: string;
59
107
  message?: string;
108
+ counts?: string;
109
+ unwitnessed?: Postcondition;
110
+ }
111
+
112
+ interface Postcondition {
113
+ name: string;
114
+ message: string;
115
+ counts?: string;
116
+ }
117
+
118
+ // An evaluation that failed during the search, with the behavior up to the state TLC was working on.
119
+ export interface EvaluationFailure {
120
+ message: string;
121
+ trace: TraceStep[];
122
+ initialState: Record<string, Value> | undefined;
123
+ exitCode: number;
60
124
  }
61
125
 
62
126
  export interface CheckResult {
63
127
  status: CheckStatus;
64
128
  violation: Violation | undefined;
129
+ failure: EvaluationFailure | undefined;
65
130
  generatedStates: number;
66
131
  distinctStates: number;
132
+ queuedStates: number;
67
133
  depth: number;
134
+ // How many states that TLC counts as expanded found each number of new states, when TLC prints
135
+ // the outdegree of the state graph.
136
+ outDegrees: number[] | undefined;
137
+ // The smallest distance between the fingerprints of two distinct states, when TLC estimates a
138
+ // collision from the actual fingerprints.
139
+ fingerprintDistance: bigint | undefined;
68
140
  }
69
141
 
70
- export interface NamedExpression {
142
+ interface NamedExpression {
71
143
  name: string;
72
144
  expression: Expression;
73
145
  scope: Scope | undefined;
74
146
  }
75
147
 
76
- export interface StateCheck extends NamedExpression {
148
+ interface StateCheck extends NamedExpression {
77
149
  variables: number[] | undefined;
150
+ membership: Membership | undefined;
78
151
  }
79
152
 
80
- export interface ActionProperty {
153
+ // A conjunct `x \in S` whose S reads no variables.
154
+ interface Membership {
155
+ variable: number;
156
+ set: Expression;
157
+ }
158
+
159
+ interface ActionProperty {
81
160
  name: string;
161
+ box: Expression;
82
162
  action: Expression;
83
163
  subscript: Expression;
84
164
  scope: Scope | undefined;
85
165
  }
86
166
 
87
- export interface Specification {
88
- init: Expression;
89
- next: Expression;
167
+ interface Specification {
168
+ init: Expression | undefined;
169
+ next: Expression | undefined;
170
+ scope: Scope | undefined;
90
171
  temporals: ScopedExpression[];
91
172
  }
92
173
 
93
- export interface Properties {
174
+ interface Properties {
94
175
  initialPredicates: NamedExpression[];
95
176
  invariants: NamedExpression[];
96
177
  actionProperties: ActionProperty[];
@@ -99,18 +180,106 @@ export interface Properties {
99
180
 
100
181
  const START: SourceLocation = { line: 0, column: 0 };
101
182
 
183
+ const INITIAL_RECOVERY_FAILURE = "Failed to recover the initial state from its fingerprint.";
184
+ const NEXT_RECOVERY_FAILURE = "Failed to recover the next state from its fingerprint.";
185
+
102
186
  const createIdentifier = (name: string): Expression => ({
103
187
  kind: "Identifier",
104
188
  name,
105
189
  location: START,
106
190
  });
107
191
 
108
- const getDefinitionBody = (name: string, environment: Environment) => {
192
+ // TLC leaves the kind out when it rejects arguments to the specification or a property.
193
+ const UNNAMED_ARGUMENT_KINDS = new Set(["name", "property"]);
194
+
195
+ // TLC checks liveness on the graph so far 3 seconds into the search and then every minute, once
196
+ // the graph has grown by a tenth and liveness checking has taken at most a fifth of the time.
197
+ const PERIODIC_START = 3000;
198
+ const PROGRESS_INTERVAL = 60_000;
199
+ const LIVENESS_GROWTH = 0.1;
200
+ const LIVENESS_RATIO = 0.2;
201
+
202
+ const getConfigOperator = (kind: string, name: string, environment: Environment) => {
109
203
  const definition = getDefinition(name, environment);
110
- if (definition?.kind !== "Operator" || definition.params.length > 0) {
111
- throw new TlaConfigError(`${name} is not defined as an operator without arguments`);
204
+ if (!definition) {
205
+ throw new TlaConfigError(
206
+ `The ${kind} ${name} specified in the configuration file\nis not defined in the specification.`,
207
+ );
112
208
  }
113
- return definition.body;
209
+ if (definition.kind === "Operator" && definition.params.length > 0) {
210
+ throw new TlaConfigError(
211
+ UNNAMED_ARGUMENT_KINDS.has(kind)
212
+ ? `TLC requires ${name} not to take any argument.`
213
+ : `TLC requires ${kind} not to take any argument, but one was given: ${name}`,
214
+ );
215
+ }
216
+ return definition;
217
+ };
218
+
219
+ const getConfigDefinition = (kind: string, name: string, environment: Environment) => {
220
+ const definition = getConfigOperator(kind, name, environment);
221
+ if (isConstantLevel(definition, environment)) {
222
+ throw new TlaConfigError(`The ${kind} ${name} cannot be a constant.`);
223
+ }
224
+ return definition;
225
+ };
226
+
227
+ // TLC evaluates every constant definition before it reads the configuration. It keeps a literal
228
+ // number or string, and a definition that fails to evaluate, as an operator.
229
+ const getConstantValue = (name: string, definition: Definition, environment: Environment) => {
230
+ if (!isConstantLevel(definition, environment)) return undefined;
231
+ if (definition.body.kind === "Number" || definition.body.kind === "String") return undefined;
232
+ try {
233
+ return evaluate(createIdentifier(name), getContext(environment, undefined, undefined));
234
+ } catch (error) {
235
+ if (error instanceof TlaEvaluationError) return undefined;
236
+ throw error;
237
+ }
238
+ };
239
+
240
+ const getConfigPredicate = (kind: string, name: string, environment: Environment) => {
241
+ const definition = getConfigOperator(kind, name, environment);
242
+ const value = getConstantValue(name, definition, environment);
243
+ if (value !== undefined && value !== true) {
244
+ throw new TlaConfigError(`The ${kind} of ${name} is equal to ${formatValue(value)}`);
245
+ }
246
+ return value === undefined ? definition : undefined;
247
+ };
248
+
249
+ const getInvariants = (names: string[], environment: Environment) => {
250
+ const analyzer = createLevelAnalyzer({
251
+ constants: new Set(environment.constants.keys()),
252
+ variables: new Set(environment.variables),
253
+ getDefinition: (name) => getDefinition(name, environment),
254
+ });
255
+ return names.flatMap((name) => {
256
+ const definition = getConfigPredicate("invariant", name, environment);
257
+ if (!definition) return [];
258
+ const levels = analyzer.analyzeDefinition(definition, new Map());
259
+ if (levels.level >= ACTION_LEVEL) {
260
+ const note =
261
+ levels.params.size === 0
262
+ ? ""
263
+ : "\nNote that a bug can cause TLC to incorrectly report this error.\nIf you believe your TLA+ or PlusCal specification to be correct,\nplease check if this bug described in LevelNode.java starting at line 590ff affects you.";
264
+ throw new TlaConfigError(
265
+ `The invariant ${name} is not a state predicate (one with no primes or temporal operators).${note}`,
266
+ );
267
+ }
268
+ return [{ name, expression: createIdentifier(name), scope: undefined }];
269
+ });
270
+ };
271
+
272
+ const toAliasRecord = (value: Value, fieldOrder: string[]) => {
273
+ if (!isFunctionValue(value)) return undefined;
274
+ const record = toFiniteFunction(value);
275
+ if (!record.domain.every((key) => typeof key === "string")) return undefined;
276
+ const entries = record.domain.map((key, index): [string, Value] => [
277
+ String(key),
278
+ record.range[index],
279
+ ]);
280
+ return Object.fromEntries(
281
+ entries.sort((left, right) => fieldOrder.indexOf(left[0]) - fieldOrder.indexOf(right[0])),
282
+ );
114
283
  };
115
284
 
116
285
  const getConjuncts = (expression: Expression, environment: Environment): Expression[] => {
@@ -125,39 +294,66 @@ const getConjuncts = (expression: Expression, environment: Environment): Express
125
294
  return [expression];
126
295
  };
127
296
 
128
- export const getSpecification = (config: ModelConfig, environment: Environment): Specification => {
297
+ const isConstantTrue = (item: ScopedExpression, environment: Environment, usage: string) => {
298
+ const conjunct = item.expression;
299
+ if (conjunct.kind !== "Identifier" || getLevel(conjunct, item.scope, environment) > 0) {
300
+ return false;
301
+ }
302
+ const value = evaluate(conjunct, getContext(environment, undefined, undefined, item.scope));
303
+ if (value === false) {
304
+ throw new TlaConfigError(`The spec is trivially false because ${conjunct.name} is false.`);
305
+ }
306
+ if (value !== true) {
307
+ throw new TlaConfigError(
308
+ `The operator ${conjunct.name}, which equals ${formatValue(value)},\ncannot be used as a ${usage}`,
309
+ );
310
+ }
311
+ return true;
312
+ };
313
+
314
+ const getSpecification = (config: ModelConfig, environment: Environment): Specification => {
129
315
  if (config.specification === undefined) {
130
- if (config.init === undefined)
131
- throw new TlaConfigError(
132
- "The configuration file did not specify the initial state predicate",
133
- );
134
- if (config.next === undefined)
135
- throw new TlaConfigError("The configuration does not specify NEXT");
136
- getDefinitionBody(config.init, environment);
137
- getDefinitionBody(config.next, environment);
316
+ const getOperator = (name: string | undefined, description: string) => {
317
+ if (name === undefined) return undefined;
318
+ const body = getConfigOperator(description, name, environment).body;
319
+ const identifier = createIdentifier(name);
320
+ // TLC evaluates a literal body later and reports that it is not a boolean.
321
+ const isLiteral = body.kind === "Number" || body.kind === "String";
322
+ if (!isLiteral && getLevel(identifier, undefined, environment) === 0) {
323
+ throw new TlaConfigError(`The ${description} ${name} cannot be a constant.`);
324
+ }
325
+ return identifier;
326
+ };
138
327
  return {
139
- init: createIdentifier(config.init),
140
- next: createIdentifier(config.next),
328
+ init: getOperator(config.init, "initial predicate"),
329
+ next: getOperator(config.next, "next state action"),
330
+ scope: undefined,
141
331
  temporals: [],
142
332
  };
143
333
  }
144
- const initConjuncts: Expression[] = [];
145
- const nextActions: Expression[] = [];
334
+ const initConjuncts: ScopedExpression[] = [];
335
+ const nextActions: ScopedExpression[] = [];
146
336
  const temporals: ScopedExpression[] = [];
147
- const body = getDefinitionBody(config.specification, environment);
148
- const getUnscoped = (expression: Expression, scope: Scope | undefined) => {
149
- const unscoped = toUnscopedExpression(expression, scope);
150
- if (!unscoped) {
151
- throw new TlaUnsupportedError(
152
- `The specification ${config.specification} has an initial predicate or next-state relation inside a quantified formula`,
337
+ const definition = getConfigOperator("name", config.specification, environment);
338
+ const value = getConstantValue(config.specification, definition, environment);
339
+ if (value !== undefined) {
340
+ throw new TlaConfigError(
341
+ `The value of ${config.specification} is equal to ${formatValue(value)}`,
342
+ );
343
+ }
344
+ expandTemporal(definition.body, undefined, environment, false).forEach((item) => {
345
+ const conjunct = item.expression;
346
+ if (isConstantTrue(item, environment, "spec")) return;
347
+ if (conjunct.kind === "UnboundedQuantifier" && conjunct.isTemporal) {
348
+ throw setExitCode(
349
+ new TlaConfigError(
350
+ "TLC does not support temporal existential, nor universal, quantification over state variables.",
351
+ ),
352
+ EXIT_STATUS.error,
153
353
  );
154
354
  }
155
- return unscoped;
156
- };
157
- expandTemporal(body, undefined, environment).forEach((item) => {
158
- const conjunct = item.expression;
159
355
  if (conjunct.kind === "Always" && conjunct.expression.kind === "BoxAction") {
160
- nextActions.push(getUnscoped(conjunct.expression.action, item.scope));
356
+ nextActions.push({ expression: conjunct.expression.action, scope: item.scope });
161
357
  return;
162
358
  }
163
359
  if (
@@ -178,21 +374,54 @@ export const getSpecification = (config: ModelConfig, environment: Environment):
178
374
  `TLC cannot handle the action-level conjunct of the specification ${config.specification}`,
179
375
  );
180
376
  }
181
- initConjuncts.push(getUnscoped(conjunct, item.scope));
377
+ initConjuncts.push(item);
182
378
  });
183
- if (nextActions.length !== 1) {
379
+ if (nextActions.length > 1) {
184
380
  throw new TlaConfigError(
185
- `The specification ${config.specification} must contain exactly one [][Next]_vars`,
381
+ `The specification ${config.specification} must contain at most one [][Next]_vars`,
186
382
  );
187
383
  }
384
+ const items = [...initConjuncts, ...nextActions];
385
+ const getName = (index: number) => `$specification${index}`;
386
+ const scope = items.reduce<Scope | undefined>(
387
+ (parent, item, index) =>
388
+ item.scope === undefined
389
+ ? parent
390
+ : {
391
+ name: getName(index),
392
+ binding: {
393
+ kind: "Thunk",
394
+ expression: item.expression,
395
+ scope: item.scope,
396
+ state: undefined,
397
+ next: undefined,
398
+ cache: undefined,
399
+ },
400
+ parent,
401
+ },
402
+ undefined,
403
+ );
404
+ const getReference = (item: ScopedExpression, index: number): Expression =>
405
+ item.scope === undefined
406
+ ? item.expression
407
+ : {
408
+ kind: "Identifier",
409
+ name: getName(index),
410
+ location: item.expression.location,
411
+ resolution: { kind: "Local" },
412
+ };
188
413
  return {
189
- init: { kind: "And", operands: initConjuncts, location: START },
190
- next: nextActions[0],
414
+ init:
415
+ initConjuncts.length === 0
416
+ ? undefined
417
+ : { kind: "And", operands: initConjuncts.map(getReference), location: START },
418
+ next: nextActions.length === 0 ? undefined : getReference(nextActions[0], initConjuncts.length),
419
+ scope,
191
420
  temporals,
192
421
  };
193
422
  };
194
423
 
195
- export const getProperties = (config: ModelConfig, environment: Environment): Properties => {
424
+ const getProperties = (config: ModelConfig, environment: Environment): Properties => {
196
425
  const properties: Properties = {
197
426
  initialPredicates: [],
198
427
  invariants: [],
@@ -200,12 +429,15 @@ export const getProperties = (config: ModelConfig, environment: Environment): Pr
200
429
  liveness: [],
201
430
  };
202
431
  config.properties.forEach((name) => {
203
- const body = getDefinitionBody(name, environment);
204
- expandTemporal(body, undefined, environment).forEach((item) => {
432
+ const definition = getConfigPredicate("property", name, environment);
433
+ if (!definition) return;
434
+ expandTemporal(definition.body, undefined, environment, true).forEach((item) => {
205
435
  const conjunct = item.expression;
436
+ if (isConstantTrue(item, environment, "property")) return;
206
437
  if (conjunct.kind === "Always" && conjunct.expression.kind === "BoxAction") {
207
438
  properties.actionProperties.push({
208
439
  name,
440
+ box: conjunct.expression,
209
441
  action: conjunct.expression.action,
210
442
  subscript: conjunct.expression.subscript,
211
443
  scope: item.scope,
@@ -233,27 +465,66 @@ export const getProperties = (config: ModelConfig, environment: Environment): Pr
233
465
  return properties;
234
466
  };
235
467
 
236
- export const getNamedExpressions = (names: string[], environment: Environment): NamedExpression[] =>
237
- names.map((name) => {
238
- getDefinitionBody(name, environment);
239
- return { name, expression: createIdentifier(name), scope: undefined };
468
+ const getNamedExpressions = (
469
+ kind: string,
470
+ names: string[],
471
+ environment: Environment,
472
+ ): NamedExpression[] =>
473
+ names.flatMap((name) =>
474
+ getConfigPredicate(kind, name, environment)
475
+ ? [{ name, expression: createIdentifier(name), scope: undefined }]
476
+ : [],
477
+ );
478
+
479
+ const getBodyRange = (name: string, environment: Environment) => {
480
+ const definition = getDefinition(name, environment);
481
+ return definition?.kind === "Operator" ? definition.bodyRange : undefined;
482
+ };
483
+
484
+ const getPossiblePredicates = (names: string[], environment: Environment) =>
485
+ names.map((name, index) => {
486
+ if (names.indexOf(name) !== index) {
487
+ throw new TlaConfigError(`_POSSIBLE lists ${name} more than once`);
488
+ }
489
+ getConfigDefinition("possible", name, environment);
490
+ const expression = createIdentifier(name);
491
+ if (getLevel(expression, undefined, environment) === TEMPORAL_LEVEL) {
492
+ throw new TlaConfigError(
493
+ `The possible of ${name} is equal to a temporal formula; only state- and action-level predicates are supported`,
494
+ );
495
+ }
496
+ return { name, expression, scope: undefined };
240
497
  });
241
498
 
242
- export const getStateChecks = (named: NamedExpression[], environment: Environment): StateCheck[] =>
499
+ const getMembership = (
500
+ expression: Expression,
501
+ variables: number[] | undefined,
502
+ environment: Environment,
503
+ ): Membership | undefined => {
504
+ if (expression.kind !== "Apply" || expression.operator !== "\\in" || variables?.length !== 1)
505
+ return undefined;
506
+ const element = expression.args[0];
507
+ if (element.kind !== "Identifier" || isLocallyResolved(element)) return undefined;
508
+ return environment.variableIndex.get(element.name) === variables[0]
509
+ ? { variable: variables[0], set: expression.args[1] }
510
+ : undefined;
511
+ };
512
+
513
+ const getStateChecks = (named: NamedExpression[], environment: Environment): StateCheck[] =>
243
514
  named.flatMap((item) =>
244
- getConjuncts(item.expression, environment).map((expression) => ({
245
- name: item.name,
246
- expression,
247
- scope: item.scope,
248
- variables: getReadVariables(expression, environment),
249
- })),
515
+ getConjuncts(item.expression, environment).map((expression) => {
516
+ const variables = getReadVariables(expression, environment);
517
+ return {
518
+ name: item.name,
519
+ expression,
520
+ scope: item.scope,
521
+ variables,
522
+ membership: getMembership(expression, variables, environment),
523
+ };
524
+ }),
250
525
  );
251
526
 
252
- export const isUnchangedFor = (
253
- stateCheck: StateCheck,
254
- state: Value[],
255
- parent: Value[] | undefined,
256
- ) => {
527
+ const isUnchangedFor = (stateCheck: StateCheck, state: Value[], parent: Value[] | undefined) => {
257
528
  const variables = stateCheck.variables;
258
529
  if (!parent || !variables) return false;
259
530
  for (let index = 0; index < variables.length; index++) {
@@ -262,10 +533,40 @@ export const isUnchangedFor = (
262
533
  return true;
263
534
  };
264
535
 
265
- export interface Search {
536
+ const WIDE_CHARACTER = /[\u0100-\uffff]/;
537
+
538
+ const DESERIALIZERS = new Set(["JsonDeserialize", "ndJsonDeserialize"]);
539
+
540
+ const isWideConfigValue = (value: ConfigValue): boolean =>
541
+ value.kind === "String"
542
+ ? WIDE_CHARACTER.test(value.value)
543
+ : value.kind === "Set" && value.elements.some(isWideConfigValue);
544
+
545
+ const isWideExpression = (expression: Expression): boolean =>
546
+ (expression.kind === "String" && WIDE_CHARACTER.test(expression.value)) ||
547
+ (expression.kind === "Apply" && DESERIALIZERS.has(expression.operator)) ||
548
+ getChildren(expression).some(isWideExpression);
549
+
550
+ // TLC fingerprints a string by the low byte of each character, so it merges states whose
551
+ // strings differ only above U+00FF. Strings reach a state from literals, the config, or files.
552
+ const hasWideString = (config: ModelConfig, environment: Environment) =>
553
+ config.constants.some(
554
+ (constant) =>
555
+ isWideConfigValue(constant.value) || (constant.args ?? []).some(isWideConfigValue),
556
+ ) ||
557
+ [...environment.definitions.values()].some(
558
+ (definition) =>
559
+ isWideExpression(definition.body) ||
560
+ (definition.kind === "Function" &&
561
+ definition.bounds.some((bound) => isWideExpression(bound.set))),
562
+ );
563
+
564
+ interface Search {
266
565
  properties: Properties;
267
566
  spec: Specification;
268
567
  getFingerprintState: (state: Value[]) => Value[];
568
+ getStoredFingerprints: (states: Value[][], fingerprintStates: Value[][]) => BigInt64Array;
569
+ getTlcOrder: () => number[];
269
570
  isSymmetric: boolean;
270
571
  findViolatedInvariant: (state: Value[], parent?: Value[]) => StateCheck | undefined;
271
572
  satisfiesConstraints: (state: Value[], parent?: Value[]) => boolean;
@@ -274,9 +575,8 @@ export interface Search {
274
575
  satisfiesActionConstraints: (state: Value[], next: Value[]) => boolean;
275
576
  trackStatePossible: (state: Value[]) => void;
276
577
  trackActionPossible: (state: Value[], next: Value[]) => void;
277
- findPostconditionViolation: (
278
- print: (text: string) => void,
279
- ) => Omit<Violation, "loopStart"> | undefined;
578
+ findUnwitnessedPossible: () => Postcondition | undefined;
579
+ findPostconditionViolation: () => Postcondition | undefined;
280
580
  }
281
581
 
282
582
  const getContext = (
@@ -284,11 +584,39 @@ const getContext = (
284
584
  state: Value[] | undefined,
285
585
  next: Value[] | undefined,
286
586
  scope?: Scope,
287
- ): Context => ({ environment, scope, state, next });
587
+ ) => ({ environment, scope, state, next });
288
588
 
289
589
  const holds = (expression: Expression, context: Context, description: string) =>
290
590
  expectBoolean(evaluate(expression, context), description);
291
591
 
592
+ // TLC names a check that is not a boolean by the location of the predicate it evaluates.
593
+ const holdsLikeTlc = (
594
+ expression: Expression,
595
+ context: Context,
596
+ getMessage = getExpectedBoolean,
597
+ ) => {
598
+ const value = evaluate(expression, context);
599
+ if (typeof value !== "boolean") {
600
+ throw new TlaEvaluationError(getMessage(expression, context.environment));
601
+ }
602
+ return value;
603
+ };
604
+
605
+ // SANY prints a number by its digits and any other expression by its location.
606
+ const getExpectedBoolean = (expression: Expression, environment: Environment) => {
607
+ const definition =
608
+ expression.kind === "Identifier" ? getDefinition(expression.name, environment) : undefined;
609
+ const body = definition?.kind === "Operator" ? definition.body : expression;
610
+ const range = definition?.kind === "Operator" ? definition.bodyRange : undefined;
611
+ const location =
612
+ body.kind === "Number"
613
+ ? (body.text ?? String(body.value))
614
+ : range
615
+ ? formatRange(range)
616
+ : describeRange(body);
617
+ return `TLC expected a boolean value, but did not find one. ${location}`;
618
+ };
619
+
292
620
  const ignorePossible = () => {};
293
621
 
294
622
  const trackPossible = (items: NamedExpression[], runtime: CheckerRuntime, context: Context) =>
@@ -320,36 +648,56 @@ export const findAssumptionViolation = (
320
648
  for (const assumption of assumptions.filter((candidate) => !candidate.isAxiom)) {
321
649
  const failure = getConstantFailure(assumption.expression, environment, "an assumption");
322
650
  if (failure) {
323
- const name =
324
- assumption.name ?? `line ${assumption.location.line}, column ${assumption.location.column}`;
325
- return { name, trace: [], message: failure.message };
651
+ return { name: describeRange(assumption.expression), trace: [], message: failure.message };
326
652
  }
327
653
  }
328
654
  return undefined;
329
655
  };
330
656
 
331
- export const createSearch = (config: ModelConfig, environment: Environment): Search | undefined => {
657
+ export const createSearch = (
658
+ config: ModelConfig,
659
+ environment: Environment,
660
+ getVariableOrder: () => string[],
661
+ ): Search | undefined => {
662
+ const configInvariants = getInvariants(config.invariants, environment);
663
+ const spec = getSpecification(config, environment);
332
664
  const properties = getProperties(config, environment);
333
- const invariants = getStateChecks(
334
- [...getNamedExpressions(config.invariants, environment), ...properties.invariants],
665
+ const invariants = getStateChecks([...configInvariants, ...properties.invariants], environment);
666
+ const isCheckingBehaviors =
667
+ invariants.length > 0 ||
668
+ properties.actionProperties.length > 0 ||
669
+ properties.liveness.length > 0;
670
+ if (
671
+ spec.init === undefined &&
672
+ (isCheckingBehaviors ||
673
+ properties.initialPredicates.length > 0 ||
674
+ environment.variables.length > 0)
675
+ ) {
676
+ throw new TlaConfigError("The configuration file did not specify the initial state predicate.");
677
+ }
678
+ if (spec.next === undefined && isCheckingBehaviors) {
679
+ throw new TlaConfigError("The configuration file did not specify the next state predicate.");
680
+ }
681
+ const constraints = getStateChecks(
682
+ getNamedExpressions("constraint", config.constraints, environment),
335
683
  environment,
336
684
  );
337
- const isConstantModel =
338
- config.specification === undefined &&
339
- config.init === undefined &&
340
- environment.variables.length === 0;
341
- if (isConstantModel) return undefined;
342
- const spec = getSpecification(config, environment);
685
+ const actionConstraints = getNamedExpressions(
686
+ "action constraint",
687
+ config.actionConstraints,
688
+ environment,
689
+ );
690
+ if (config.rlReward !== undefined) getConfigOperator("rlreward", config.rlReward, environment);
691
+ if (config.periodic !== undefined) getConfigOperator("periodic", config.periodic, environment);
692
+ const possible = getPossiblePredicates(config.possible, environment);
343
693
  if (environment.variables.length === 0) return undefined;
344
694
  const symmetryGroup =
345
695
  config.symmetry === undefined ? [] : getSymmetryGroup(config.symmetry, environment);
696
+ if (config.view !== undefined) getConfigOperator("view function", config.view, environment);
346
697
  const view =
347
- config.view === undefined ? undefined : getNamedExpressions([config.view], environment)[0];
348
- const constraints = getStateChecks(
349
- getNamedExpressions(config.constraints, environment),
350
- environment,
351
- );
352
- const actionConstraints = getNamedExpressions(config.actionConstraints, environment);
698
+ config.view === undefined
699
+ ? undefined
700
+ : { name: config.view, expression: createIdentifier(config.view), scope: undefined };
353
701
  const actionProperties = properties.actionProperties.map((property) => {
354
702
  const unchanged: Expression = {
355
703
  kind: "Unchanged",
@@ -358,72 +706,135 @@ export const createSearch = (config: ModelConfig, environment: Environment): Sea
358
706
  };
359
707
  return { ...property, unchanged };
360
708
  });
361
- const possible = getNamedExpressions(config.possible, environment);
362
709
  const isActionPossible = (item: NamedExpression) =>
363
710
  getLevel(item.expression, undefined, environment) >= ACTION_LEVEL;
364
711
  const statePossible = possible.filter((item) => !isActionPossible(item));
365
712
  const actionPossible = possible.filter(isActionPossible);
366
713
  const runtime = environment.runtime;
714
+ const tlcOrder = { indices: undefined as number[] | undefined };
715
+ const getTlcOrder = () => {
716
+ if (tlcOrder.indices) return tlcOrder.indices;
717
+ const variableOrder = getVariableOrder();
718
+ const getTlcPosition = (index: number) => {
719
+ const position = variableOrder.indexOf(environment.variables[index]);
720
+ return position === -1 ? environment.variables.length : position;
721
+ };
722
+ tlcOrder.indices = environment.variables
723
+ .map((_, index) => index)
724
+ .sort((left, right) => getTlcPosition(left) - getTlcPosition(right));
725
+ return tlcOrder.indices;
726
+ };
727
+ // A representative in TLC's variable order is the one whose fingerprint TLC reports.
728
+ const order = symmetryGroup.length > 0 ? getTlcOrder() : undefined;
729
+ const getViewValue = (expression: Expression, state: Value[]) =>
730
+ evaluate(expression, getContext(environment, state, undefined));
731
+ const getTlcStateFingerprint = (state: Value[]) => {
732
+ const indices = getTlcOrder();
733
+ const representative =
734
+ symmetryGroup.length === 0 ? state : getRepresentative(state, symmetryGroup, indices);
735
+ return getTlcFingerprint(
736
+ view === undefined
737
+ ? indices.map((index) => representative[index])
738
+ : [getViewValue(view.expression, representative)],
739
+ );
740
+ };
741
+ const isFingerprintedLikeTlc = hasWideString(config, environment);
742
+ runtime.getFingerprint = getTlcStateFingerprint;
743
+ const findUnwitnessedPossible = () => {
744
+ const unwitnessed = possible.find((item) => !runtime.possibleCounts.get(item.name));
745
+ if (!unwitnessed) return undefined;
746
+ const range = getBodyRange(unwitnessed.name, environment);
747
+ const location = range ? ` at ${formatRange(range)}` : "";
748
+ return {
749
+ name: unwitnessed.name,
750
+ message: `The _POSSIBLE predicate ${unwitnessed.name}${location} was never witnessed.\nOthers may be unwitnessed too; only witnessed predicates appear with a\nnon-zero count in the record printed above.\nSee https://explain.tlapl.us/possible-conditions for additional details.`,
751
+ counts: prettyPrint(formatValue(getPossibleCounts(runtime), true)),
752
+ };
753
+ };
367
754
  return {
368
755
  properties,
369
756
  spec,
370
757
  isSymmetric: symmetryGroup.length > 0,
758
+ getTlcOrder,
759
+ getStoredFingerprints: (states, fingerprintStates) => {
760
+ if (view !== undefined || isFingerprintedLikeTlc) {
761
+ return BigInt64Array.from(states, getTlcStateFingerprint);
762
+ }
763
+ const indices = getTlcOrder();
764
+ const getFingerprint = createTlcFingerprinter();
765
+ return BigInt64Array.from(fingerprintStates, (state) =>
766
+ getFingerprint(indices.map((index) => state[index])),
767
+ );
768
+ },
371
769
  getFingerprintState: (state) => {
770
+ if (isFingerprintedLikeTlc) return [String(getTlcStateFingerprint(state))];
372
771
  const representative =
373
- symmetryGroup.length === 0 ? state : getRepresentative(state, symmetryGroup);
374
- return view === undefined
375
- ? representative
376
- : [evaluate(view.expression, getContext(environment, representative, undefined))];
772
+ symmetryGroup.length === 0 ? state : getRepresentative(state, symmetryGroup, order);
773
+ return view === undefined ? representative : [getViewValue(view.expression, representative)];
377
774
  },
378
775
  findViolatedInvariant: (state, parent) =>
379
- invariants.find(
380
- (invariant) =>
381
- !isUnchangedFor(invariant, state, parent) &&
382
- !holds(
383
- invariant.expression,
384
- getContext(environment, state, undefined, invariant.scope),
385
- `invariant ${invariant.name}`,
386
- ),
387
- ),
776
+ invariants.find((invariant) => {
777
+ if (isUnchangedFor(invariant, state, parent)) return false;
778
+ try {
779
+ const context = getContext(environment, state, undefined, invariant.scope);
780
+ const membership = invariant.membership;
781
+ // The parent satisfies every invariant, so only the entries the step changed can fail.
782
+ return parent && membership
783
+ ? !isUpdatedElementOf(
784
+ state[membership.variable],
785
+ parent[membership.variable],
786
+ evaluate(membership.set, context),
787
+ )
788
+ : !holdsLikeTlc(invariant.expression, context);
789
+ } catch (error) {
790
+ // TLC reports a failure only on a state after the initial states as an invariant failure.
791
+ if (!parent) throw error;
792
+ throw withHeadline(
793
+ setExitCode(error, EXIT_STATUS.safetyEvaluationFailure),
794
+ `Evaluating invariant ${invariant.name} failed.`,
795
+ );
796
+ }
797
+ }),
388
798
  satisfiesConstraints: (state, parent) =>
389
799
  constraints.every(
390
800
  (constraint) =>
391
801
  isUnchangedFor(constraint, state, parent) ||
392
- holds(
393
- constraint.expression,
394
- getContext(environment, state, undefined),
395
- `constraint ${constraint.name}`,
396
- ),
802
+ holdsLikeTlc(constraint.expression, getContext(environment, state, undefined)),
397
803
  ),
398
804
  findFailedInitialPredicate: (state) =>
399
805
  properties.initialPredicates.find(
400
806
  (predicate) =>
401
- !holds(
807
+ !holdsLikeTlc(
402
808
  predicate.expression,
403
809
  getContext(environment, state, undefined, predicate.scope),
404
- `property ${predicate.name}`,
405
810
  ),
406
811
  ),
407
812
  findViolatedActionProperty: (state, next) =>
408
- actionProperties.find(
409
- (property) =>
410
- !holds(
411
- property.action,
412
- getContext(environment, state, next, property.scope),
413
- `property ${property.name}`,
414
- ) &&
415
- !holds(
416
- property.unchanged,
417
- getContext(environment, state, next, property.scope),
418
- "a subscript",
419
- ),
420
- ),
813
+ actionProperties.find((property) => {
814
+ try {
815
+ return (
816
+ !holdsLikeTlc(
817
+ property.action,
818
+ getContext(environment, state, next, property.scope),
819
+ () =>
820
+ `Attempted to evaluate an expression of form [A]_e, but A was not a boolean.\n${describeRange(property.box)}`,
821
+ ) &&
822
+ !holds(
823
+ property.unchanged,
824
+ getContext(environment, state, next, property.scope),
825
+ "a subscript",
826
+ )
827
+ );
828
+ } catch (error) {
829
+ throw withHeadline(error, `Evaluating action property ${property.name} failed.`);
830
+ }
831
+ }),
421
832
  satisfiesActionConstraints: (state, next) =>
422
833
  actionConstraints.every((constraint) =>
423
- holds(
834
+ holdsLikeTlc(
424
835
  constraint.expression,
425
836
  getContext(environment, state, next),
426
- `action constraint ${constraint.name}`,
837
+ (expression) => `${UNEXPECTED_EXCEPTION}${getExpectedBoolean(expression, environment)}`,
427
838
  ),
428
839
  ),
429
840
  trackStatePossible:
@@ -436,20 +847,14 @@ export const createSearch = (config: ModelConfig, environment: Environment): Sea
436
847
  ? ignorePossible
437
848
  : (state, next) =>
438
849
  trackPossible(actionPossible, runtime, getContext(environment, state, next)),
439
- findPostconditionViolation: (print) => {
440
- const unwitnessed = possible.find((item) => !runtime.possibleCounts.get(item.name));
441
- if (unwitnessed) {
442
- print(formatValue(getPossibleCounts(runtime), true));
443
- return {
444
- name: unwitnessed.name,
445
- trace: [],
446
- message: `The _POSSIBLE predicate ${unwitnessed.name} was never witnessed.`,
447
- };
448
- }
850
+ findUnwitnessedPossible,
851
+ findPostconditionViolation: () => {
852
+ const unwitnessed = findUnwitnessedPossible();
853
+ if (unwitnessed) return unwitnessed;
449
854
  for (const name of config.postconditions) {
450
855
  const failure = getConstantFailure(createIdentifier(name), environment, "a postcondition");
451
856
  if (failure) {
452
- return { name, trace: [], message: failure.message ?? `Postcondition ${name} is false.` };
857
+ return { name, message: failure.message ?? `Postcondition ${name} is false.` };
453
858
  }
454
859
  }
455
860
  return undefined;
@@ -457,37 +862,114 @@ export const createSearch = (config: ModelConfig, environment: Environment): Sea
457
862
  };
458
863
  };
459
864
 
460
- export const check = (options: CheckOptions): CheckResult => {
865
+ const withHeadline = (error: unknown, headline: string) =>
866
+ error instanceof TlaEvaluationError
867
+ ? setExitCode(
868
+ new TlaEvaluationError(`${headline}\n${error.message}`, error),
869
+ getErrorExitCode(error),
870
+ )
871
+ : error;
872
+
873
+ export const checkSequentially = (options: CheckOptions): CheckResult => {
874
+ setNextStatePhase(false);
461
875
  const config = typeof options.config === "string" ? parseConfig(options.config) : options.config;
462
- const print = options.onPrint ?? console.log;
463
- const specification = createEnvironment(parseModule(options.source), config, {
876
+ const onPrint = options.onPrint ?? console.log;
877
+ // TLC prints again while it rebuilds a trace, between the states it prints. Printing those lines
878
+ // before the trace would misplace them, so rebuilding a trace prints nothing.
879
+ const output = { isMuted: false };
880
+ const print = (text: string) => {
881
+ if (!output.isMuted) onPrint(text);
882
+ };
883
+ const withoutOutput = <Result>(rebuild: () => Result) => {
884
+ output.isMuted = true;
885
+ const result = rebuild();
886
+ output.isMuted = false;
887
+ return result;
888
+ };
889
+ setStringOrder(getTlcStringOrder(options.source, config, options.loadModule));
890
+ const specification = createEnvironment(config, {
891
+ source: options.source,
464
892
  loadModule: options.loadModule,
893
+ loadClass: options.loadClass,
465
894
  print,
466
895
  files: { readFile: options.readFile, writeFile: options.writeFile },
896
+ seed: options.seed,
467
897
  });
468
898
  const environment = specification.environment;
469
899
  const runtime = environment.runtime;
900
+ runtime.pause = options.onPause ?? (() => {});
901
+ runtime.getSpecification = () =>
902
+ getSpecificationValue(
903
+ config,
904
+ environment,
905
+ specification.variableLocations,
906
+ specification.instanceActions,
907
+ );
470
908
  const statistics = { depth: 0 };
471
909
  const createResult = (
472
910
  status: CheckStatus,
473
911
  violation?: Omit<Violation, "loopStart"> & { loopStart?: number },
912
+ failure?: EvaluationFailure,
474
913
  ): CheckResult => ({
475
914
  status,
476
915
  violation: violation && { ...violation, loopStart: violation.loopStart },
916
+ failure,
477
917
  generatedStates: runtime.generatedStates,
478
918
  distinctStates: runtime.distinctStates,
479
- depth: statistics.depth,
919
+ queuedStates: runtime.queueSize,
920
+ depth: runtime.generatedStates === 0 ? 0 : Math.max(statistics.depth, 1),
921
+ outDegrees: undefined,
922
+ fingerprintDistance: undefined,
923
+ });
924
+ const outDegrees = Array.from({ length: OUT_DEGREE_BUCKETS }, () => 0);
925
+ const expansion = { newStates: 0 };
926
+ const getOutDegreeBucket = () => Math.min(expansion.newStates, OUT_DEGREE_BUCKETS - 1);
927
+ // TLC counts the state it was expanding when an evaluation failed.
928
+ const getPartialOutDegrees = () =>
929
+ outDegrees.map((count, degree) => (degree === getOutDegreeBucket() ? count + 1 : count));
930
+ const createSuccess = (): CheckResult => ({
931
+ ...createResult("success"),
932
+ outDegrees: [...outDegrees],
933
+ fingerprintDistance: getFingerprintDistance(
934
+ runtime.distinctStates,
935
+ runtime.generatedStates,
936
+ () =>
937
+ search
938
+ ? search.getStoredFingerprints(states, fingerprintStates)
939
+ : BigInt64Array.from(states, runtime.getFingerprint),
940
+ ),
480
941
  });
481
942
 
943
+ const search = createSearch(config, environment, () =>
944
+ getTlcVariableOrder(options.source, options.loadModule),
945
+ );
482
946
  const assumptionViolation = findAssumptionViolation(specification.assumptions, environment);
483
947
  if (assumptionViolation) return createResult("assumption-violation", assumptionViolation);
484
-
485
- const search = createSearch(config, environment);
486
- if (!search) return createResult("success");
487
- const properties = search.properties;
948
+ if (!search) return createSuccess();
949
+ const hasPostconditions = config.postconditions.length > 0 || config.possible.length > 0;
950
+ const reportViolation = (
951
+ status: CheckStatus,
952
+ violation: Omit<Violation, "loopStart"> & { loopStart?: number },
953
+ getLoopAction?: () => string | undefined,
954
+ ) => {
955
+ if (hasPostconditions) {
956
+ const start = violation.loopStart;
957
+ runtime.counterExample = createCounterExample(
958
+ violation.trace,
959
+ start === undefined || !getLoopAction ? undefined : { start, action: getLoopAction() },
960
+ );
961
+ }
962
+ const unwitnessed = search.findUnwitnessedPossible();
963
+ if (!unwitnessed) search.findPostconditionViolation();
964
+ return createResult(status, unwitnessed ? { ...violation, unwitnessed } : violation);
965
+ };
488
966
  const spec = search.spec;
489
967
  const getFingerprintState = search.getFingerprintState;
490
- const liveness = createLivenessChecker(properties.liveness, spec.temporals, environment);
968
+ const nextActions = { value: undefined as SpecAction[] | undefined };
969
+ const isReducing = config.view !== undefined || config.symmetry !== undefined;
970
+ const liveness = withLivenessExitCode(() =>
971
+ createLivenessChecker(search.properties.liveness, spec.temporals, environment),
972
+ );
491
973
  const isCanonicalizedFirst = search.isSymmetric || liveness !== undefined;
492
974
 
493
975
  const states: Value[][] = [];
@@ -498,30 +980,146 @@ export const check = (options: CheckOptions): CheckResult => {
498
980
  const buckets = new Map<number, number | number[]>();
499
981
  const canonicalizeState = createCanonicalizer();
500
982
 
501
- const toRecord = (state: Value[]) =>
502
- Object.fromEntries(environment.variables.map((name, index) => [name, state[index]]));
503
- const getTrace = (
504
- index: number,
505
- last?: { state: Value[]; action: string | undefined },
506
- ): TraceStep[] => {
507
- const steps: TraceStep[] = last ? [{ action: last.action, state: toRecord(last.state) }] : [];
508
- for (let current = index; current !== -1; current = parents[current]) {
509
- steps.push({ action: actions[current], state: toRecord(states[current]) });
983
+ const toRecord = (state: Value[]): Record<string, Value> =>
984
+ Object.fromEntries(
985
+ search.getTlcOrder().map((index) => [environment.variables[index], state[index]]),
986
+ );
987
+ const getAliasState = (
988
+ alias: string,
989
+ steps: Successor[],
990
+ position: number,
991
+ loopStart: number | undefined,
992
+ ) => {
993
+ const state = steps[position].state;
994
+ const next = (steps[position + 1] ?? steps[loopStart ?? position]).state;
995
+ // TLC evaluates TLCGet("level") and Trace in an alias at the state's position in the trace.
996
+ runtime.getLevel = () => position + 1;
997
+ runtime.getBehavior = () => steps.slice(0, position + 1).map((step) => step.state);
998
+ try {
999
+ const body = getConfigDefinition("alias", alias, environment).body;
1000
+ const value = evaluate(createIdentifier(alias), getContext(environment, state, next));
1001
+ const fieldOrder = body.kind === "Record" ? body.fields.map((field) => field.name) : [];
1002
+ return toAliasRecord(value, fieldOrder) ?? toRecord(state);
1003
+ } catch (error) {
1004
+ if (!(error instanceof TlaConfigError || error instanceof TlaEvaluationError)) throw error;
1005
+ return { ...toRecord(state), _ALIASEvalError: error.message };
510
1006
  }
511
- return steps.reverse();
512
- };
513
- const getPathTrace = (path: number[]) =>
514
- path.map((stateIndex, position): TraceStep => {
515
- if (position === 0) return { action: undefined, state: toRecord(states[stateIndex]) };
516
- const previous = path[position - 1];
517
- const action =
518
- previous === stateIndex
519
- ? "Stuttering"
520
- : getSuccessors(spec.next, states[previous], environment).find((successor) =>
521
- isSameState(successor.state, states[stateIndex]),
522
- )?.action;
523
- return { action, state: toRecord(states[stateIndex]) };
1007
+ };
1008
+ // TLC labels a step with the first action that takes it, evaluated as when the search expanded
1009
+ // the previous state.
1010
+ const getLabel = (index: number, previous: Value[], state: Value[]) => {
1011
+ nextActions.value ??= getNextActions(config, environment, specification.instanceActions);
1012
+ const expanding = { ...current };
1013
+ Object.assign(current, { index, isExpanding: true, candidate: undefined });
1014
+ const fingerprintState = getFingerprintState(state);
1015
+ const action = nextActions.value.find((item) =>
1016
+ getSuccessors(item.expression, previous, environment, item.scope).some((successor) =>
1017
+ isSameState(getFingerprintState(successor.state), fingerprintState),
1018
+ ),
1019
+ );
1020
+ Object.assign(current, expanding);
1021
+ return action && getActionLabel(action);
1022
+ };
1023
+ const toTrace = (steps: Successor[], path: number[], loopStart?: number): TraceStep[] => {
1024
+ const alias = config.alias;
1025
+ const labels = withoutOutput(() => {
1026
+ // TLC rebuilds a trace from the initial predicate, which can reset what TLCSet stored.
1027
+ if (steps.length > 1 && isImpure(environment)) getSpecInitialStates();
1028
+ // TLC finds the action that takes each step before it evaluates the alias.
1029
+ return steps.map((step, position) =>
1030
+ position === 0 || step.action === "Stuttering"
1031
+ ? undefined
1032
+ : getLabel(path[position - 1], steps[position - 1].state, step.state),
1033
+ );
524
1034
  });
1035
+ return steps.map((step, position) => ({
1036
+ action: step.action,
1037
+ label: labels[position],
1038
+ state:
1039
+ alias === undefined
1040
+ ? toRecord(step.state)
1041
+ : getAliasState(alias, steps, position, loopStart),
1042
+ }));
1043
+ };
1044
+ const getSpecInitialStates = () =>
1045
+ spec.init === undefined ? [] : getInitialStates(spec.init, environment, spec.scope);
1046
+ const getTraceSuccessors = (state: Value[]) =>
1047
+ spec.next === undefined ? [] : getSuccessors(spec.next, state, environment, spec.scope);
1048
+ const hasFingerprint = (state: Value[], index: number) =>
1049
+ isSameState(getFingerprintState(state), fingerprintStates[index]);
1050
+ const findSuccessorWithFingerprint = (state: Value[], index: number) =>
1051
+ getTraceSuccessors(state).find((successor) => hasFingerprint(successor.state, index));
1052
+ const getPathStates = (path: number[], nextFailure: string) => {
1053
+ const initial =
1054
+ isReducing || isImpure(environment)
1055
+ ? getSpecInitialStates().find((state) => hasFingerprint(state, path[0]))
1056
+ : states[path[0]];
1057
+ if (!initial) throw new TlaEvaluationError(INITIAL_RECOVERY_FAILURE);
1058
+ const steps: Successor[] = [{ state: initial, action: undefined }];
1059
+ for (let position = 1; position < path.length; position++) {
1060
+ const previous = steps[position - 1].state;
1061
+ if (path[position - 1] === path[position]) {
1062
+ steps.push({ state: previous, action: "Stuttering" });
1063
+ continue;
1064
+ }
1065
+ const successor = findSuccessorWithFingerprint(previous, path[position]);
1066
+ if (!successor) throw new TlaEvaluationError(nextFailure);
1067
+ steps.push(successor);
1068
+ }
1069
+ return steps;
1070
+ };
1071
+ const getTrace = (index: number, last?: Successor) => {
1072
+ const path: number[] = [];
1073
+ for (let position = index; position !== -1; position = parents[position]) {
1074
+ path.unshift(position);
1075
+ }
1076
+ const steps =
1077
+ isReducing && path.length > 1
1078
+ ? getPathStates(path, INITIAL_RECOVERY_FAILURE)
1079
+ : path.map((position) => ({ state: states[position], action: actions[position] }));
1080
+ if (!last) return toTrace(steps, path);
1081
+ const action = isReducing
1082
+ ? getTraceSuccessors(states[index]).find((successor) =>
1083
+ isSameState(successor.state, last.state),
1084
+ )?.action
1085
+ : last.action;
1086
+ return toTrace([...steps, { state: last.state, action }], path);
1087
+ };
1088
+ // TLC prints an initial state on its own without evaluating the alias.
1089
+ const getStateTrace = (index: number) =>
1090
+ parents[index] === -1
1091
+ ? [{ action: undefined, label: undefined, state: toRecord(states[index]) }]
1092
+ : getTrace(index);
1093
+ // TLC names the initial state it was checking unless a standard module's Java code failed.
1094
+ const toFailure = (
1095
+ error: unknown,
1096
+ trace: TraceStep[],
1097
+ initialState?: Value[],
1098
+ failureOutDegrees?: number[],
1099
+ ) => {
1100
+ if (!(error instanceof TlaEvaluationError)) throw error;
1101
+ return {
1102
+ ...createResult("error", undefined, {
1103
+ message: error.message,
1104
+ trace,
1105
+ initialState:
1106
+ initialState && !(error instanceof TlaModuleError) ? toRecord(initialState) : undefined,
1107
+ exitCode: getErrorExitCode(error),
1108
+ }),
1109
+ outDegrees: failureOutDegrees,
1110
+ };
1111
+ };
1112
+ const getPathTrace = (path: number[], loopStart?: number) => {
1113
+ const steps = getPathStates(path, NEXT_RECOVERY_FAILURE);
1114
+ const last = steps[steps.length - 1].state;
1115
+ const isClosed =
1116
+ !isReducing ||
1117
+ loopStart === undefined ||
1118
+ loopStart === path.length - 1 ||
1119
+ findSuccessorWithFingerprint(last, path[loopStart]) !== undefined;
1120
+ if (!isClosed) throw new TlaEvaluationError(NEXT_RECOVERY_FAILURE);
1121
+ return toTrace(steps, path, loopStart);
1122
+ };
525
1123
  const getStateHash = (state: Value[]) => {
526
1124
  let hash = 0x811c9dc5;
527
1125
  for (let index = 0; index < state.length; index++)
@@ -572,21 +1170,32 @@ export const check = (options: CheckOptions): CheckResult => {
572
1170
  isExpanding: false,
573
1171
  candidate: undefined as Value[] | undefined,
574
1172
  candidateLevel: 0,
1173
+ livenessSource: -1,
575
1174
  };
576
1175
  const getPath = (index: number): Value[][] =>
577
1176
  index === -1 ? [] : [...getPath(parents[index]), states[index]];
1177
+ runtime.isSeen = (state) => {
1178
+ const fingerprintState = getFingerprintState(state);
1179
+ return findStateIndex(getStateHash(fingerprintState), fingerprintState) !== -1;
1180
+ };
578
1181
  runtime.getBehavior = (state) => {
579
1182
  const index = state === current.candidate ? -1 : states.indexOf(state);
580
1183
  return index === -1 ? [...getPath(current.index), state] : getPath(index);
581
1184
  };
1185
+ runtime.getCurrentState = () => (current.index === -1 ? undefined : states[current.index]);
1186
+ runtime.setLivenessSource = (index) => {
1187
+ current.livenessSource = index;
1188
+ };
582
1189
  runtime.getLevel = (state) => {
1190
+ const source = current.livenessSource;
1191
+ if (source !== -1) return state === states[source] ? depths[source] : depths[source] + 1;
583
1192
  if (state === current.candidate) return current.candidateLevel;
584
1193
  if (current.index === -1) return 0;
585
1194
  if (state === states[current.index]) return depths[current.index];
586
1195
  return current.isExpanding ? depths[current.index] + 1 : 0;
587
1196
  };
588
1197
 
589
- for (const state of getInitialStates(spec.init, environment)) {
1198
+ const visitInitialState = (state: Value[]) => {
590
1199
  canonicalizeState(state);
591
1200
  runtime.generatedStates++;
592
1201
  runtime.initialStates++;
@@ -594,10 +1203,10 @@ export const check = (options: CheckOptions): CheckResult => {
594
1203
  current.candidateLevel = 1;
595
1204
  const fingerprintState = getFingerprintState(state);
596
1205
  const hash = getStateHash(fingerprintState);
597
- const isSeen = findStateIndex(hash, fingerprintState) !== -1;
598
- const isInModel = isSeen || search.satisfiesConstraints(state);
1206
+ const isInModel = search.satisfiesConstraints(state);
599
1207
  if (isInModel) search.trackStatePossible(state);
600
- if (isSeen) continue;
1208
+ const isSeen = isInModel && findStateIndex(hash, fingerprintState) !== -1;
1209
+ if (isSeen) return undefined;
601
1210
  if (isInModel) {
602
1211
  countDistinctState(1);
603
1212
  runtime.queueSize++;
@@ -605,100 +1214,203 @@ export const check = (options: CheckOptions): CheckResult => {
605
1214
  }
606
1215
  const violated = search.findViolatedInvariant(state);
607
1216
  if (violated) {
608
- return createResult("invariant-violation", {
1217
+ return reportViolation("invariant-violation", {
609
1218
  name: violated.name,
610
- trace: [{ action: undefined, state: toRecord(state) }],
1219
+ trace: toTrace([{ action: undefined, state }], []),
611
1220
  });
612
1221
  }
613
1222
  const failedPredicate = search.findFailedInitialPredicate(state);
614
1223
  if (failedPredicate) {
615
- return createResult("liveness-violation", {
1224
+ return reportViolation("liveness-violation", {
616
1225
  name: failedPredicate.name,
617
- trace: [{ action: undefined, state: toRecord(state) }],
1226
+ trace: toTrace([{ action: undefined, state }], []),
618
1227
  });
619
1228
  }
620
- if (!isInModel) continue;
1229
+ if (!isInModel) return undefined;
621
1230
  markSeen(hash, states.length);
622
1231
  addState(state, fingerprintState, -1, undefined);
623
- }
624
-
625
- for (let index = 0; index < states.length && !runtime.isStopped; index++) {
1232
+ return undefined;
1233
+ };
1234
+ const visitSuccessor = (index: number, successor: Successor, liveSuccessors: LiveSuccessor[]) => {
626
1235
  const state = states[index];
627
- current.index = index;
628
- runtime.queueSize = states.length - index - 1;
629
- current.isExpanding = true;
630
- const successors = getSuccessors(spec.next, state, environment);
631
- current.isExpanding = false;
632
- if (successors.length === 0 && config.checkDeadlock) {
633
- return createResult("deadlock", { name: "deadlock", trace: getTrace(index) });
1236
+ runtime.generatedStates++;
1237
+ current.candidate = successor.state;
1238
+ current.candidateLevel = depths[index] + 1;
1239
+ if (isCanonicalizedFirst) canonicalizeState(successor.state);
1240
+ const fingerprintState = getFingerprintState(successor.state);
1241
+ const hash = getStateHash(fingerprintState);
1242
+ const found = findStateIndex(hash, fingerprintState);
1243
+ const isStateInModel = search.satisfiesConstraints(successor.state, state);
1244
+ if (isStateInModel) search.trackStatePossible(successor.state);
1245
+ const isInModel = isStateInModel && search.satisfiesActionConstraints(state, successor.state);
1246
+ if (isInModel) search.trackActionPossible(state, successor.state);
1247
+ const existing = isInModel ? found : -1;
1248
+ if (existing !== -1 && liveness) {
1249
+ const stored = states[existing];
1250
+ const isStored = stored.every((value, position) => value === successor.state[position]);
1251
+ liveSuccessors.push({ index: existing, state: isStored ? stored : successor.state });
634
1252
  }
635
- const liveSuccessors: LiveSuccessor[] = [];
636
- for (const successor of successors) {
637
- runtime.generatedStates++;
638
- current.candidate = successor.state;
639
- current.candidateLevel = depths[index] + 1;
640
- if (isCanonicalizedFirst) canonicalizeState(successor.state);
641
- const fingerprintState = getFingerprintState(successor.state);
642
- const hash = getStateHash(fingerprintState);
643
- const found = findStateIndex(hash, fingerprintState);
644
- const isStateInModel = found !== -1 || search.satisfiesConstraints(successor.state, state);
645
- if (isStateInModel) search.trackStatePossible(successor.state);
646
- const isInModel = isStateInModel && search.satisfiesActionConstraints(state, successor.state);
647
- if (isInModel) search.trackActionPossible(state, successor.state);
648
- const existing = isInModel ? found : -1;
649
- if (existing !== -1 && liveness) {
650
- const stored = states[existing];
651
- const isStored = stored.every((value, position) => value === successor.state[position]);
652
- liveSuccessors.push({ index: existing, state: isStored ? stored : successor.state });
653
- }
654
- const isNew = isInModel && existing === -1;
655
- if (isNew) countDistinctState(depths[index] + 1);
656
- if (existing === -1) {
1253
+ const isNew = isInModel && existing === -1;
1254
+ if (isNew) {
1255
+ countDistinctState(depths[index] + 1);
1256
+ expansion.newStates++;
1257
+ }
1258
+ if (existing === -1) {
1259
+ try {
657
1260
  const violated = search.findViolatedInvariant(successor.state, state);
658
1261
  if (violated) {
659
- return createResult("invariant-violation", {
1262
+ return reportViolation("invariant-violation", {
660
1263
  name: violated.name,
661
1264
  trace: getTrace(index, successor),
662
1265
  });
663
1266
  }
1267
+ } catch (error) {
1268
+ // TLC prints the outdegree when it cannot reproduce the failure, as for an invariant here.
1269
+ return toFailure(error, getTrace(index, successor), undefined, getPartialOutDegrees());
664
1270
  }
665
- const violatedProperty = search.findViolatedActionProperty(state, successor.state);
666
- if (violatedProperty) {
667
- return createResult("liveness-violation", {
668
- name: violatedProperty.name,
669
- trace: getTrace(index, successor),
670
- });
671
- }
672
- if (!isNew) continue;
673
- if (!isCanonicalizedFirst) canonicalizeState(successor.state);
674
- markSeen(hash, states.length);
675
- if (liveness) liveSuccessors.push({ index: states.length, state: successor.state });
676
- addState(successor.state, fingerprintState, index, successor.action);
677
- runtime.queueSize++;
678
1271
  }
679
- const accepted = liveness?.addState(index, state, liveSuccessors);
680
- if (accepted) {
681
- return createResult("property-violation", {
1272
+ const violatedProperty = search.findViolatedActionProperty(state, successor.state);
1273
+ if (violatedProperty) {
1274
+ return reportViolation("liveness-violation", {
1275
+ name: violatedProperty.name,
1276
+ trace: getTrace(index, successor),
1277
+ });
1278
+ }
1279
+ if (!isNew) return undefined;
1280
+ if (!isCanonicalizedFirst) canonicalizeState(successor.state);
1281
+ markSeen(hash, states.length);
1282
+ if (liveness) liveSuccessors.push({ index: states.length, state: successor.state });
1283
+ addState(successor.state, fingerprintState, index, successor.action);
1284
+ runtime.queueSize++;
1285
+ return undefined;
1286
+ };
1287
+
1288
+ const outcome: { result: CheckResult | undefined } = { result: undefined };
1289
+ if (spec.init !== undefined) {
1290
+ try {
1291
+ forEachInitialState(
1292
+ spec.init,
1293
+ environment,
1294
+ (state) => {
1295
+ try {
1296
+ outcome.result = visitInitialState(state);
1297
+ } catch (error) {
1298
+ outcome.result = toFailure(error, [], state);
1299
+ }
1300
+ return outcome.result !== undefined;
1301
+ },
1302
+ spec.scope,
1303
+ );
1304
+ } catch (error) {
1305
+ return toFailure(error, []);
1306
+ }
1307
+ }
1308
+ if (outcome.result) return outcome.result;
1309
+
1310
+ const next = spec.next;
1311
+ if (next === undefined) {
1312
+ if (states.length > 0) {
1313
+ throw new TlaEvaluationError(
1314
+ "No next state actions defined to generate successor states from.",
1315
+ );
1316
+ }
1317
+ return createSuccess();
1318
+ }
1319
+ const expandState = (index: number) => {
1320
+ const state = states[index];
1321
+ const liveSuccessors: LiveSuccessor[] = [];
1322
+ const successorCount = forEachSuccessor(
1323
+ next,
1324
+ state,
1325
+ environment,
1326
+ (successor) => {
1327
+ try {
1328
+ outcome.result = visitSuccessor(index, successor, liveSuccessors);
1329
+ } catch (error) {
1330
+ outcome.result = toFailure(error, getTrace(index, successor));
1331
+ }
1332
+ return outcome.result !== undefined;
1333
+ },
1334
+ spec.scope,
1335
+ );
1336
+ current.isExpanding = false;
1337
+ if (outcome.result) return outcome.result;
1338
+ if (successorCount === 0 && config.checkDeadlock) {
1339
+ return reportViolation("deadlock", { name: "deadlock", trace: getStateTrace(index) });
1340
+ }
1341
+ try {
1342
+ const accepted = liveness?.addState(index, state, liveSuccessors);
1343
+ current.livenessSource = -1;
1344
+ if (!accepted) return undefined;
1345
+ return reportViolation("property-violation", {
682
1346
  name: accepted.name,
683
1347
  trace: getPathTrace(accepted.path),
684
1348
  });
1349
+ } catch (error) {
1350
+ return toFailure(error, getStateTrace(index), undefined, getPartialOutDegrees());
1351
+ }
1352
+ };
1353
+ const reportLasso = (lasso: Lasso) => {
1354
+ const path = [...lasso.prefix, ...lasso.cycle];
1355
+ const trace = getPathTrace(path, lasso.prefix.length);
1356
+ const back = path[lasso.prefix.length];
1357
+ const last = path[path.length - 1];
1358
+ const loopLabel =
1359
+ back === last ? undefined : withoutOutput(() => getLabel(last, states[last], states[back]));
1360
+ return reportViolation(
1361
+ "liveness-violation",
1362
+ { name: lasso.name, trace, loopStart: lasso.prefix.length, loopLabel },
1363
+ () =>
1364
+ back === last
1365
+ ? trace[trace.length - 1].action
1366
+ : getTraceSuccessors(states[last]).find((successor) =>
1367
+ isSameState(successor.state, states[back]),
1368
+ )?.action,
1369
+ );
1370
+ };
1371
+ const isPeriodic = liveness !== undefined && options.livenessCheck !== "final";
1372
+ const startedAt = performance.now();
1373
+ const periodic = { at: startedAt + PERIODIC_START, size: 1, time: 0 };
1374
+ const findPeriodicViolation = (expanded: number) => {
1375
+ const now = performance.now();
1376
+ periodic.at = now + PROGRESS_INTERVAL;
1377
+ const isGrown = (expanded - periodic.size) / periodic.size > LIVENESS_GROWTH;
1378
+ if (!isGrown || periodic.time > (now - startedAt) * LIVENESS_RATIO) return undefined;
1379
+ periodic.size = expanded;
1380
+ const lasso = liveness?.findViolation();
1381
+ current.livenessSource = -1;
1382
+ periodic.time += performance.now() - now;
1383
+ return lasso;
1384
+ };
1385
+ setNextStatePhase(true);
1386
+ for (let index = 0; index < states.length && !runtime.isStopped; index++) {
1387
+ current.index = index;
1388
+ current.candidate = undefined;
1389
+ runtime.queueSize = states.length - index - 1;
1390
+ current.isExpanding = true;
1391
+ try {
1392
+ outcome.result = expandState(index);
1393
+ } catch (error) {
1394
+ outcome.result = toFailure(error, getStateTrace(index));
1395
+ }
1396
+ if (outcome.result) return outcome.result;
1397
+ outDegrees[getOutDegreeBucket()]++;
1398
+ expansion.newStates = 0;
1399
+ if (isPeriodic && performance.now() >= periodic.at) {
1400
+ const lasso = findPeriodicViolation(index + 1);
1401
+ if (lasso) return reportLasso(lasso);
685
1402
  }
686
1403
  }
687
1404
 
688
1405
  current.index = -1;
689
1406
  current.candidate = undefined;
690
1407
  const lasso = liveness?.findViolation();
691
- if (lasso) {
692
- return createResult("liveness-violation", {
693
- name: lasso.name,
694
- trace: getPathTrace([...lasso.prefix, ...lasso.cycle]),
695
- loopStart: lasso.prefix.length,
696
- });
697
- }
1408
+ current.livenessSource = -1;
1409
+ if (lasso) return reportLasso(lasso);
698
1410
 
699
- const postconditionViolation = search.findPostconditionViolation(print);
1411
+ const postconditionViolation = search.findPostconditionViolation();
700
1412
  if (postconditionViolation) {
701
- return createResult("postcondition-violation", postconditionViolation);
1413
+ return createResult("postcondition-violation", { ...postconditionViolation, trace: [] });
702
1414
  }
703
- return createResult("success");
1415
+ return createSuccess();
704
1416
  };