tla-ts 0.0.3-dev.d9ff6f2 → 0.0.3-dev.e8bef80

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 (81) hide show
  1. package/dist/cli.cjs +1 -1
  2. package/dist/cli.js +1 -1
  3. package/dist/index.cjs +1 -1
  4. package/dist/index.d.cts +166 -40
  5. package/dist/index.d.ts +166 -40
  6. package/dist/index.js +1 -1
  7. package/dist/parallel-worker.cjs +1 -1
  8. package/dist/parallel-worker.js +2 -2
  9. package/dist/parallel.cjs +1 -1
  10. package/dist/parallel.js +2 -2
  11. package/dist/run-cli.cjs +1351 -22
  12. package/dist/run-cli.js +1351 -22
  13. package/dist/transfer.cjs +83 -34
  14. package/dist/transfer.js +83 -34
  15. package/package.json +5 -1
  16. package/src/ast.ts +55 -7
  17. package/src/bags.ts +4 -7
  18. package/src/builtins.ts +29 -11
  19. package/src/bundled-modules.ts +3 -3
  20. package/src/canonical.ts +4 -3
  21. package/src/check.ts +1331 -367
  22. package/src/cli.ts +8 -1
  23. package/src/codegen.ts +68 -21
  24. package/src/config.ts +226 -207
  25. package/src/environment.ts +423 -127
  26. package/src/errors.ts +168 -9
  27. package/src/evaluate.ts +720 -177
  28. package/src/exit-codes.ts +6 -24
  29. package/src/index.ts +1 -0
  30. package/src/instances.ts +3 -1
  31. package/src/java-overrides.ts +104 -25
  32. package/src/levels.ts +149 -31
  33. package/src/lexer.ts +122 -29
  34. package/src/live-check.ts +204 -148
  35. package/src/liveness.ts +191 -122
  36. package/src/obligation-expression.ts +2 -2
  37. package/src/obligation-source.ts +2 -0
  38. package/src/parallel-worker.ts +6 -1
  39. package/src/parallel.ts +57 -6
  40. package/src/parser.ts +428 -141
  41. package/src/pcal-ast.ts +770 -0
  42. package/src/pcal-parse.ts +1523 -0
  43. package/src/pcal-tokenize.ts +516 -0
  44. package/src/pcal-translate.ts +1230 -0
  45. package/src/pcal-validate.ts +454 -0
  46. package/src/randomization.ts +24 -7
  47. package/src/resolve.ts +1436 -459
  48. package/src/run-cli.ts +1166 -181
  49. package/src/runtime.ts +16 -0
  50. package/src/sany-builtins.ts +147 -0
  51. package/src/sany-generator.ts +3128 -0
  52. package/src/sany-levels.ts +1208 -0
  53. package/src/sany-lexer.ts +545 -0
  54. package/src/sany-linter.ts +122 -0
  55. package/src/sany-modules.ts +1398 -0
  56. package/src/sany-nodes.ts +463 -0
  57. package/src/sany-parse-error.ts +2161 -0
  58. package/src/sany-report.ts +356 -0
  59. package/src/sany-selectors.ts +738 -0
  60. package/src/sany-source.ts +248 -0
  61. package/src/sany-xml.ts +1017 -0
  62. package/src/spec-description.ts +25 -5
  63. package/src/standard-modules.ts +203 -146
  64. package/src/standard-ranges.ts +116 -0
  65. package/src/state-graph.ts +29 -6
  66. package/src/subexpressions.ts +221 -161
  67. package/src/substitution-levels.ts +38 -17
  68. package/src/successors.ts +161 -167
  69. package/src/symmetry.ts +168 -50
  70. package/src/tableau.ts +3 -1
  71. package/src/tlc-ext.ts +13 -17
  72. package/src/tlc-messages.ts +329 -0
  73. package/src/tlc-module.ts +49 -21
  74. package/src/tlc-modules.ts +0 -4
  75. package/src/tlc-order.ts +55 -9
  76. package/src/tlc-random.ts +28 -3
  77. package/src/tlc-replay.ts +655 -0
  78. package/src/tlc-version.ts +18 -0
  79. package/src/transfer.ts +15 -3
  80. package/src/value-sources.ts +29 -0
  81. package/src/values.ts +680 -255
package/src/check.ts CHANGED
@@ -12,24 +12,32 @@ import { createEnvironment } from "./environment";
12
12
  import {
13
13
  getErrorExitCode,
14
14
  isStackOverflow,
15
- formatRange,
16
- STACK_OVERFLOW,
17
15
  TlaConfigError,
18
16
  TlaEvaluationError,
19
- TlaIncompleteStateError,
17
+ TlaIllegalStateError,
18
+ TlaIncompleteSuccessorError,
20
19
  TlaModuleError,
20
+ TlaStackOverflowError,
21
+ getUnexpectedException,
21
22
  UNEXPECTED_EXCEPTION,
22
23
  } from "./errors";
23
- import { EXIT_STATUS, setExitCode, withLivenessExitCode } from "./exit-codes";
24
+ import type { JavaOverride } from "./java-overrides";
25
+ import { EXIT_STATUS, getExitCode, setExitCode, withLivenessExitCode } from "./exit-codes";
24
26
  import {
27
+ describeNode,
25
28
  describeRange,
29
+ createTracingEnvironment,
26
30
  evaluate,
31
+ evaluateStartupDefinitions,
27
32
  expectBoolean,
33
+ formatRange,
28
34
  getDefinition,
29
35
  isConstantLevel,
30
36
  isImpure,
37
+ type CallStack,
31
38
  type Context,
32
39
  type Environment,
40
+ type FingerprintFailure,
33
41
  type Scope,
34
42
  } from "./evaluate";
35
43
  import {
@@ -51,8 +59,10 @@ import {
51
59
  import {
52
60
  getActionLabel,
53
61
  getActionSignature,
62
+ getInitActions,
54
63
  getNextActions,
55
64
  getSpecificationValue,
65
+ toActionValue,
56
66
  type SpecAction,
57
67
  } from "./spec-description";
58
68
  import {
@@ -62,22 +72,35 @@ import {
62
72
  type StateWriter,
63
73
  } from "./state-graph";
64
74
  import { getRepresentative, getSymmetryGroup } from "./symmetry";
65
- import { getTlcStringOrder, getTlcDeclarationOrder } from "./tlc-order";
75
+ import { getTlcStringOrder, getTlcVariableOrder } from "./tlc-order";
76
+ import {
77
+ formatNestedMessage,
78
+ getCodedMessage,
79
+ isEvalException,
80
+ MESSAGE_CODE,
81
+ MISSING_INIT_174,
82
+ } from "./tlc-messages";
83
+ import { replayInitialStates, replaySuccessors } from "./tlc-replay";
66
84
  import { createTlcFingerprinter, getTlcFingerprint } from "./tlc-random";
67
85
  import { createCanonicalizer } from "./canonical";
68
86
  import { getPossibleCounts, type CheckerRuntime } from "./runtime";
69
- import { createCounterExample } from "./tlc-ext";
87
+ import { createActionRecord, createCounterExample } from "./tlc-ext";
70
88
  import { getFingerprintDistance, OUT_DEGREE_BUCKETS } from "./tlc-summary";
89
+ import type { TlcVersion } from "./tlc-version";
71
90
  import {
72
91
  combineHash,
73
92
  createModelValue,
74
93
  formatState,
75
94
  formatValue,
95
+ getHeldValues,
96
+ getFingerprintError,
97
+ markFingerprinted,
76
98
  getValueHash,
77
99
  isFunctionValue,
78
100
  isSameValue,
79
101
  isUpdatedElementOf,
80
102
  setStringOrder,
103
+ setValueVersion,
81
104
  toFiniteFunction,
82
105
  type Value,
83
106
  } from "./values";
@@ -97,8 +120,71 @@ export interface CheckOptions {
97
120
  livenessCheck?: "default" | "final";
98
121
  // TLC's -dump: writes the reachable states, or with `dot` the state graph, through writeFile.
99
122
  dump?: StateDump;
123
+ // TLC's -tool, which changes the messages of TLC's errors.
124
+ isTool?: boolean;
125
+ // Whether TLC records a binary trace for its trace exploration spec, for which it loads Integers.
126
+ isTraceRecorded?: boolean;
127
+ // Whether the caller printed SANY's report, its warnings included, before the check.
128
+ isSanyReported?: boolean;
129
+ // False for TLC's -nowarning, which changes how TLC computes the successors of some actions.
130
+ isWarningEnabled?: boolean;
131
+ // The TLC whose output tla-ts reproduces, which changes how TLC labels an action.
132
+ version?: TlcVersion;
133
+ // Reports the points of the search at which TLC prints a message.
134
+ onProgress?: (progress: CheckProgress) => void;
135
+ }
136
+
137
+ export interface InitialStatesProgress {
138
+ kind: "initial-states-progress";
139
+ count: number;
100
140
  }
101
141
 
142
+ // A check that TLC's DoInitFunctor reports as violated before it stops its replay of the initial
143
+ // states.
144
+ export interface InitialStateViolation {
145
+ kind: "initial-state-violation";
146
+ status: "invariant-violation" | "liveness-violation";
147
+ name: string;
148
+ state: Record<string, Value>;
149
+ }
150
+
151
+ // A line the spec prints, or what TLC reports as it replays the initial states.
152
+ export type OutputLine = string | InitialStatesProgress | InitialStateViolation;
153
+
154
+ // The spec is parsed, TLC warns about each invariant that is a true constant formula and each
155
+ // property that is a state formula, finds the branches of the temporal properties, computes the
156
+ // initial states, reporting each time their count reaches a power of two, reports how far the
157
+ // search got 3 seconds after it starts and every minute after, and checks the temporal properties
158
+ // on the state graph so far at those times and on the complete state graph at the end.
159
+ export type CheckProgress =
160
+ | { kind: "parsed" }
161
+ | { kind: "constant-level-invariant"; name: string }
162
+ | { kind: "state-level-property"; name: string }
163
+ | { kind: "liveness-initializing"; isSymmetric: boolean; isConstrained: boolean }
164
+ | { kind: "liveness-prepared"; branches: number }
165
+ | { kind: "initial-states-started" }
166
+ | InitialStatesProgress
167
+ | { kind: "initial-states-computed"; initialStates: InitialStates }
168
+ | { kind: "progress"; statistics: SearchStatistics }
169
+ | {
170
+ kind: "liveness-started";
171
+ branches: number;
172
+ // Whether TLC checks the complete state graph, and how many states of it each branch has.
173
+ isComplete: boolean;
174
+ states: number;
175
+ statistics: SearchStatistics;
176
+ }
177
+ | { kind: "liveness-finished" }
178
+ // A warning TLC prints as it evaluates the spec, with its message code.
179
+ | { kind: "warning"; code: number; text: string }
180
+ // A method of the class named after a module, which TLC reports as it loads the class.
181
+ | ({ kind: "java-override" } & JavaOverride);
182
+
183
+ export interface SearchStatistics extends Pick<
184
+ CheckResult,
185
+ "generatedStates" | "distinctStates" | "queuedStates" | "depth"
186
+ > {}
187
+
102
188
  export type CheckStatus =
103
189
  | "success"
104
190
  | "assumption-violation"
@@ -114,6 +200,9 @@ export interface TraceStep {
114
200
  // TLC's name, parameters and location for the action that took this step.
115
201
  label: string | undefined;
116
202
  state: Record<string, Value>;
203
+ // What the spec prints, before TLC prints this step, as TLC evaluates it again to rebuild the
204
+ // trace. The first step has what TLC prints before the trace.
205
+ output?: OutputLine[];
117
206
  }
118
207
 
119
208
  export interface Violation {
@@ -121,32 +210,64 @@ export interface Violation {
121
210
  // Every temporal property that a liveness counterexample violates, in the configuration's order.
122
211
  properties?: string[];
123
212
  trace: TraceStep[];
213
+ // What the spec prints after TLC prints the states of the trace, as TLC finds the step back into
214
+ // the cycle of a lasso or rebuilds the trace once more.
215
+ traceOutput?: OutputLine[];
124
216
  loopStart: number | undefined;
125
217
  loopLabel?: string;
126
218
  message?: string;
127
219
  counts?: string;
128
220
  unwitnessed?: Postcondition;
221
+ // A POSTCONDITION that is false or fails after the counterexample, which TLC checks as it
222
+ // prints one.
223
+ postcondition?: Postcondition;
224
+ // What TLC warns about after a counterexample, with its code.
225
+ warning?: { code: number; text: string };
129
226
  }
130
227
 
131
228
  interface Postcondition {
132
229
  name: string;
230
+ // TLC's message code.
231
+ code: number;
133
232
  message: string;
134
233
  counts?: string;
135
234
  }
136
235
 
137
236
  // An evaluation that failed during the search, with the behavior up to the state TLC was working on.
138
237
  export interface EvaluationFailure {
238
+ // TLC's code for the message, and its text with and without -tool.
239
+ code: number;
139
240
  message: string;
241
+ toolMessage: string;
140
242
  trace: TraceStep[];
243
+ traceOutput?: OutputLine[];
141
244
  initialState: Record<string, Value> | undefined;
142
245
  exitCode: number;
143
- replay?: Replay;
246
+ // The expressions TLC was evaluating when the failure occurred, outermost first, when TLC finds
247
+ // them by replaying the failure.
248
+ callStack: Expression[] | undefined;
249
+ // Whether TLC prints the call stack before the error, as it does for a failed liveness check.
250
+ isCallStackFirst?: boolean;
251
+ // The FingerprintException the replay raises, which TLC reports in place of the call stack.
252
+ fingerprint?: FingerprintFailure;
253
+ // How TLC reports failing again as it prints the trace, since it can't fingerprint the state the
254
+ // failure occurred in.
255
+ traceFailure?: FailureMessage;
256
+ // A POSTCONDITION that is false or fails after the trace, which TLC checks as it prints one.
257
+ postcondition?: Postcondition;
258
+ // Whether TLC stops before it prints the statistics, as it does for an illegal initial state.
259
+ isWithoutStatistics?: boolean;
144
260
  }
145
261
 
146
- // TLC replays a failed step to print the expressions it was evaluating when the replay failed.
147
- export interface Replay {
148
- output: string[];
149
- callStack: string[] | undefined;
262
+ // Where TLC's replay of a failure fails.
263
+ interface ReplayFailure {
264
+ callStack: Expression[];
265
+ fingerprint: FingerprintFailure | undefined;
266
+ }
267
+
268
+ export interface InitialStates {
269
+ generated: number;
270
+ distinct: number;
150
271
  }
151
272
 
152
273
  export interface CheckResult {
@@ -157,14 +278,55 @@ export interface CheckResult {
157
278
  distinctStates: number;
158
279
  queuedStates: number;
159
280
  depth: number;
281
+ // How many initial states TLC generated and how many of them were distinct, once it computed
282
+ // them all without a violation or an error.
283
+ initialStates: InitialStates | undefined;
160
284
  // How many states that TLC counts as expanded found each number of new states, when TLC prints
161
285
  // the outdegree of the state graph.
162
286
  outDegrees: number[] | undefined;
163
287
  // The smallest distance between the fingerprints of two distinct states, when TLC estimates a
164
288
  // collision from the actual fingerprints.
165
289
  fingerprintDistance: bigint | undefined;
290
+ // A temporal property TLC finds violated as it adds a deadlocked state to the behavior graph,
291
+ // which it reports after the deadlock.
292
+ additionalViolation?: Violation;
293
+ // Where TLC's worker fails to add the state to the behavior graph after it reports a violation.
294
+ liveCallStack?: Expression[];
295
+ // How many states that TLC counts as expanded found each number of new states, when its workers
296
+ // stop on a violation without an error code, which TLC 1.7.4 reports as a successful search.
297
+ violationOutDegrees?: number[];
298
+ }
299
+
300
+ interface Behavior {
301
+ trace: TraceStep[];
302
+ traceOutput?: OutputLine[];
303
+ }
304
+
305
+ interface TraceOptions {
306
+ loopStart?: number;
307
+ known?: number;
308
+ }
309
+
310
+ interface FailureOptions {
311
+ initialState?: Value[];
312
+ isInitial?: boolean;
313
+ outDegrees?: number[];
314
+ callStack?: Expression[];
315
+ fingerprint?: FingerprintFailure;
316
+ isNextState?: boolean;
317
+ isCallStackFirst?: boolean;
318
+ traceFailure?: FailureMessage;
319
+ // Whether the call stack is of adding the state to the behavior graph, which TLC prints instead
320
+ // of replaying the error.
321
+ isLiveCallStack?: boolean;
166
322
  }
167
323
 
324
+ // TLC prints what the spec prints as it replays a failure after the trace.
325
+ const appendTraceOutput = <Traced extends Behavior>(behavior: Traced, lines: OutputLine[]) => ({
326
+ ...behavior,
327
+ traceOutput: [...(behavior.traceOutput ?? []), ...lines],
328
+ });
329
+
168
330
  interface NamedExpression {
169
331
  name: string;
170
332
  expression: Expression;
@@ -174,6 +336,8 @@ interface NamedExpression {
174
336
  interface StateCheck extends NamedExpression {
175
337
  variables: number[] | undefined;
176
338
  membership: Membership | undefined;
339
+ // The whole predicate that TLC evaluates for the check, of which the expression is a conjunct.
340
+ predicate: Expression;
177
341
  }
178
342
 
179
343
  // A conjunct `x \in S` whose S reads no variables.
@@ -242,14 +406,6 @@ const getConfigOperator = (kind: string, name: string, environment: Environment)
242
406
  return definition;
243
407
  };
244
408
 
245
- const getConfigDefinition = (kind: string, name: string, environment: Environment) => {
246
- const definition = getConfigOperator(kind, name, environment);
247
- if (isConstantLevel(definition, environment)) {
248
- throw new TlaConfigError(`The ${kind} ${name} cannot be a constant.`);
249
- }
250
- return definition;
251
- };
252
-
253
409
  // TLC evaluates every constant definition before it reads the configuration. It keeps a literal
254
410
  // number or string, and a definition that fails to evaluate, as an operator.
255
411
  const getConstantValue = (name: string, definition: Definition, environment: Environment) => {
@@ -258,20 +414,77 @@ const getConstantValue = (name: string, definition: Definition, environment: Env
258
414
  try {
259
415
  return evaluate(createIdentifier(name), getContext(environment, undefined, undefined));
260
416
  } catch (error) {
417
+ // TLC swallows whatever the definition throws, a stack overflow included.
261
418
  if (error instanceof TlaEvaluationError || isStackOverflow(error)) return undefined;
262
419
  throw error;
263
420
  }
264
421
  };
265
422
 
266
- const getConfigPredicate = (kind: string, name: string, environment: Environment) => {
423
+ // TLC takes for an operator only a definition it hasn't replaced with its value.
424
+ const getConfigDefinition = (kind: string, name: string, environment: Environment) => {
267
425
  const definition = getConfigOperator(kind, name, environment);
268
- const value = getConstantValue(name, definition, environment);
426
+ if (getConstantValue(name, definition, environment) !== undefined) {
427
+ throw new TlaConfigError(`The ${kind} ${name} cannot be a constant.`);
428
+ }
429
+ return definition;
430
+ };
431
+
432
+ // TLC also takes a constant that the configuration assigns a value, which must be TRUE.
433
+ const getConfigPredicate = (kind: string, name: string, environment: Environment) => {
434
+ const definition = environment.constants.has(name)
435
+ ? undefined
436
+ : getConfigOperator(kind, name, environment);
437
+ const value = definition
438
+ ? getConstantValue(name, definition, environment)
439
+ : environment.constants.get(name);
269
440
  if (value !== undefined && value !== true) {
270
441
  throw new TlaConfigError(`The ${kind} of ${name} is equal to ${formatValue(value)}`);
271
442
  }
272
443
  return value === undefined ? definition : undefined;
273
444
  };
274
445
 
446
+ // TLC reports how many initial states it has computed each time the count is a power of two.
447
+ export const reportInitialStatesProgress = (
448
+ count: number,
449
+ onProgress: ((progress: InitialStatesProgress) => void) | undefined,
450
+ ) => {
451
+ if (count > 1 && (count & (count - 1)) === 0) {
452
+ onProgress?.({ kind: "initial-states-progress", count });
453
+ }
454
+ };
455
+
456
+ // What TLC does once SANY is done: it computes the constant definitions, then warns about each
457
+ // invariant that is a true constant formula, which it doesn't check. TLC prints each distinct
458
+ // warning once.
459
+ export const reportStartup = (
460
+ specification: {
461
+ environment: Environment;
462
+ startupDefinitions: Definition[];
463
+ javaOverrides: JavaOverride[];
464
+ },
465
+ config: ModelConfig,
466
+ onProgress: CheckOptions["onProgress"],
467
+ ) => {
468
+ const environment = specification.environment;
469
+ const warned = new Set<string>();
470
+ environment.runtime.warn = (code, text) => {
471
+ if (warned.has(text)) return;
472
+ warned.add(text);
473
+ onProgress?.({ kind: "warning", code, text });
474
+ };
475
+ onProgress?.({ kind: "parsed" });
476
+ // TLC loads the classes of the modules before it computes the constant definitions.
477
+ specification.javaOverrides.forEach((override) =>
478
+ onProgress?.({ kind: "java-override", ...override }),
479
+ );
480
+ evaluateStartupDefinitions(specification.startupDefinitions, environment);
481
+ config.invariants.forEach((name) => {
482
+ if (!getConfigPredicate("invariant", name, environment)) {
483
+ onProgress?.({ kind: "constant-level-invariant", name });
484
+ }
485
+ });
486
+ };
487
+
275
488
  const getInvariants = (names: string[], environment: Environment) => {
276
489
  const analyzer = createLevelAnalyzer({
277
490
  constants: new Set(environment.constants.keys()),
@@ -344,14 +557,8 @@ const getSpecification = (config: ModelConfig, environment: Environment): Specif
344
557
  if (config.specification === undefined) {
345
558
  const getOperator = (name: string | undefined, description: string) => {
346
559
  if (name === undefined) return undefined;
347
- const body = getConfigOperator(description, name, environment).body;
348
- const identifier = createIdentifier(name);
349
- // TLC evaluates a literal body later and reports that it is not a boolean.
350
- const isLiteral = body.kind === "Number" || body.kind === "String";
351
- if (!isLiteral && getLevel(identifier, undefined, environment) === 0) {
352
- throw new TlaConfigError(`The ${description} ${name} cannot be a constant.`);
353
- }
354
- return identifier;
560
+ getConfigDefinition(description, name, environment);
561
+ return createIdentifier(name);
355
562
  };
356
563
  return {
357
564
  init: getOperator(config.init, "initial predicate"),
@@ -360,6 +567,11 @@ const getSpecification = (config: ModelConfig, environment: Environment): Specif
360
567
  temporals: [],
361
568
  };
362
569
  }
570
+ if (config.init !== undefined || config.next !== undefined) {
571
+ throw new TlaConfigError(
572
+ "The configuration file cannot specify both INIT/NEXT and SPECIFICATION fields.",
573
+ );
574
+ }
363
575
  const initConjuncts: ScopedExpression[] = [];
364
576
  const nextActions: ScopedExpression[] = [];
365
577
  const temporals: ScopedExpression[] = [];
@@ -389,8 +601,9 @@ const getSpecification = (config: ModelConfig, environment: Environment): Specif
389
601
  conjunct.kind === "Always" &&
390
602
  getLevel(conjunct.expression, item.scope, environment) < ACTION_LEVEL
391
603
  ) {
604
+ // TLC accepts the spec and fails when it builds the tableau of the temporal formulas.
392
605
  throw setExitCode(
393
- new TlaConfigError(
606
+ new TlaEvaluationError(
394
607
  `TLC cannot handle the temporal formula ${describeRange(conjunct.expression)}`,
395
608
  ),
396
609
  EXIT_STATUS.error,
@@ -453,7 +666,11 @@ const getSpecification = (config: ModelConfig, environment: Environment): Specif
453
666
  };
454
667
  };
455
668
 
456
- const getProperties = (config: ModelConfig, environment: Environment): Properties => {
669
+ const getProperties = (
670
+ config: ModelConfig,
671
+ environment: Environment,
672
+ onProgress: CheckOptions["onProgress"],
673
+ ): Properties => {
457
674
  const properties: Properties = {
458
675
  initialPredicates: [],
459
676
  invariants: [],
@@ -463,12 +680,21 @@ const getProperties = (config: ModelConfig, environment: Environment): Propertie
463
680
  config.properties.forEach((name) => {
464
681
  const definition = getConfigPredicate("property", name, environment);
465
682
  if (!definition) return;
466
- expandTemporal(definition.body, undefined, environment, true, name).forEach((item) => {
683
+ // TLC checks a property that is a state formula only on the initial states, so it warns about
684
+ // one as it processes the property, before the constraints.
685
+ if (getLevel(definition.body, undefined, environment) === 1) {
686
+ onProgress?.({ kind: "state-level-property", name });
687
+ }
688
+ // TLC 1.7.4 expands a property as it does a specification, so it doesn't unroll one that
689
+ // quantifies over a constant set.
690
+ const isProperty = environment.runtime.version !== "1.7.4";
691
+ expandTemporal(definition.body, undefined, environment, isProperty).forEach((item) => {
467
692
  const conjunct = item.expression;
468
693
  if (isConstantTrue(item, environment, "property")) return;
694
+ const partName = item.name ?? name;
469
695
  if (conjunct.kind === "Always" && conjunct.expression.kind === "BoxAction") {
470
696
  properties.actionProperties.push({
471
- name: item.name,
697
+ name: partName,
472
698
  box: conjunct.expression,
473
699
  action: conjunct.expression.action,
474
700
  subscript: conjunct.expression.subscript,
@@ -480,11 +706,17 @@ const getProperties = (config: ModelConfig, environment: Environment): Propertie
480
706
  conjunct.kind === "Always" &&
481
707
  getLevel(conjunct.expression, item.scope, environment) <= 1
482
708
  ) {
483
- // TLC names the invariant []P after P when P is an operator name.
484
- const expression = conjunct.expression;
709
+ // TLC names the invariant by the operator the property asserts always holds, when it
710
+ // applies the operator to no arguments. The name of an operator another module defines
711
+ // resolves to its key, so the name comes from its definition.
712
+ const body = conjunct.expression;
713
+ const operator =
714
+ body.kind === "Identifier" && !isLocallyResolved(body)
715
+ ? getDefinition(body.name, environment)
716
+ : undefined;
485
717
  properties.invariants.push({
486
- name: expression.kind === "Identifier" ? expression.name : item.name,
487
- expression,
718
+ name: operator?.name ?? (body.kind === "Identifier" ? body.name : partName),
719
+ expression: body,
488
720
  scope: item.scope,
489
721
  });
490
722
  return;
@@ -492,7 +724,7 @@ const getProperties = (config: ModelConfig, environment: Environment): Propertie
492
724
  const level = getLevel(conjunct, item.scope, environment);
493
725
  if (level < ACTION_LEVEL) {
494
726
  properties.initialPredicates.push({
495
- name: item.name,
727
+ name: partName,
496
728
  expression: conjunct,
497
729
  scope: item.scope,
498
730
  });
@@ -552,6 +784,17 @@ const getMembership = (
552
784
  : undefined;
553
785
  };
554
786
 
787
+ // TLC evaluates the body of an invariant that the configuration names.
788
+ const getPredicate = (expression: Expression, environment: Environment) => {
789
+ if (expression.kind !== "Identifier" || environment.constants.has(expression.name)) {
790
+ return expression;
791
+ }
792
+ const definition = getDefinition(expression.name, environment);
793
+ return definition?.kind === "Operator" && definition.params.length === 0
794
+ ? definition.body
795
+ : expression;
796
+ };
797
+
555
798
  const getStateChecks = (named: NamedExpression[], environment: Environment): StateCheck[] =>
556
799
  named.flatMap((item) =>
557
800
  getConjuncts(item.expression, environment).map((expression) => {
@@ -564,6 +807,7 @@ const getStateChecks = (named: NamedExpression[], environment: Environment): Sta
564
807
  scope: item.scope,
565
808
  variables,
566
809
  membership: getMembership(expression, variables, environment),
810
+ predicate: getPredicate(item.expression, environment),
567
811
  };
568
812
  }),
569
813
  );
@@ -612,7 +856,25 @@ interface Search {
612
856
  getStoredFingerprints: (states: Value[][], fingerprintStates: Value[][]) => BigInt64Array;
613
857
  getTlcOrder: () => number[];
614
858
  isSymmetric: boolean;
859
+ // TLC drops a constraint that is a true constant formula.
860
+ isConstrained: boolean;
615
861
  findViolatedInvariant: (state: Value[], parent?: Value[]) => StateCheck | undefined;
862
+ // The checks of a state that TLC evaluates when it replays the computation of the initial states
863
+ // or of the successors of a state, with an environment that records the call stack. The first
864
+ // returns the check that stops the replay, and the second false where TLC stops it.
865
+ // TLC fingerprints a replayed state that satisfies the constraints before it checks the rest.
866
+ checkReplayedInitialState: (
867
+ state: Value[],
868
+ tracing: Environment,
869
+ addFingerprint: () => void,
870
+ ) => Pick<InitialStateViolation, "status" | "name"> | undefined;
871
+ // Adding the fingerprint of a successor tells whether TLC had not seen it yet.
872
+ checkReplayedSuccessor: (
873
+ state: Value[],
874
+ next: Value[],
875
+ tracing: Environment,
876
+ addFingerprint: () => boolean,
877
+ ) => boolean;
616
878
  satisfiesConstraints: (state: Value[], parent?: Value[]) => boolean;
617
879
  findFailedInitialPredicate: (state: Value[]) => NamedExpression | undefined;
618
880
  findViolatedActionProperty: (state: Value[], next: Value[]) => ActionProperty | undefined;
@@ -620,7 +882,8 @@ interface Search {
620
882
  trackStatePossible: (state: Value[]) => void;
621
883
  trackActionPossible: (state: Value[], next: Value[]) => void;
622
884
  findUnwitnessedPossible: () => Postcondition | undefined;
623
- findPostconditionViolation: () => Postcondition | undefined;
885
+ // After a counterexample, TLC skips the postconditions when one of them is constant.
886
+ findPostconditionViolation: (isAfterViolation?: boolean) => Postcondition | undefined;
624
887
  }
625
888
 
626
889
  const getContext = (
@@ -646,21 +909,23 @@ const holdsLikeTlc = (
646
909
  return value;
647
910
  };
648
911
 
649
- // SANY prints a number by its digits and any other expression by its location.
650
912
  const getExpectedBoolean = (expression: Expression, environment: Environment) => {
651
913
  const definition =
652
914
  expression.kind === "Identifier" ? getDefinition(expression.name, environment) : undefined;
653
915
  const body = definition?.kind === "Operator" ? definition.body : expression;
654
916
  const range = definition?.kind === "Operator" ? definition.bodyRange : undefined;
655
- const location =
656
- body.kind === "Number"
657
- ? (body.text ?? String(body.value))
658
- : range
659
- ? formatRange(range)
660
- : describeRange(body);
917
+ const location = range && body.kind !== "Number" ? formatRange(range) : describeNode(body);
661
918
  return `TLC expected a boolean value, but did not find one. ${location}`;
662
919
  };
663
920
 
921
+ // TLC evaluates the whole predicate of a check, which fails at a conjunct that isn't a boolean as
922
+ // the conjunction does.
923
+ const holdsAsConjunct = (check: StateCheck, context: Context) =>
924
+ holdsLikeTlc(check.expression, context, (expression, environment) => {
925
+ holdsLikeTlc(check.predicate, context);
926
+ return getExpectedBoolean(expression, environment);
927
+ });
928
+
664
929
  const ignorePossible = () => {};
665
930
 
666
931
  const trackPossible = (items: NamedExpression[], runtime: CheckerRuntime, context: Context) =>
@@ -702,11 +967,16 @@ export const createSearch = (
702
967
  config: ModelConfig,
703
968
  environment: Environment,
704
969
  getVariableOrder: () => string[],
970
+ onProgress?: CheckOptions["onProgress"],
705
971
  ): Search | undefined => {
706
972
  const configInvariants = getInvariants(config.invariants, environment);
707
973
  const spec = getSpecification(config, environment);
708
- const properties = getProperties(config, environment);
974
+ const properties = getProperties(config, environment, onProgress);
709
975
  const invariants = getStateChecks([...configInvariants, ...properties.invariants], environment);
976
+ // The invariants TLC evaluates, each of which may have several conjuncts among the checks.
977
+ const invariantPredicates = [
978
+ ...new Map(invariants.map((invariant) => [invariant.predicate, invariant])).values(),
979
+ ];
710
980
  const isCheckingBehaviors =
711
981
  invariants.length > 0 ||
712
982
  properties.actionProperties.length > 0 ||
@@ -717,7 +987,11 @@ export const createSearch = (
717
987
  properties.initialPredicates.length > 0 ||
718
988
  environment.variables.length > 0)
719
989
  ) {
720
- throw new TlaConfigError("The configuration file did not specify the initial state predicate.");
990
+ throw new TlaConfigError(
991
+ environment.runtime.version === "1.7.4"
992
+ ? MISSING_INIT_174
993
+ : "The configuration file did not specify the initial state predicate.",
994
+ );
721
995
  }
722
996
  if (spec.next === undefined && isCheckingBehaviors) {
723
997
  throw new TlaConfigError("The configuration file did not specify the next state predicate.");
@@ -736,7 +1010,9 @@ export const createSearch = (
736
1010
  const possible = getPossiblePredicates(config.possible, environment);
737
1011
  if (environment.variables.length === 0) return undefined;
738
1012
  const symmetryGroup =
739
- config.symmetry === undefined ? [] : getSymmetryGroup(config.symmetry, environment);
1013
+ config.symmetry === undefined
1014
+ ? undefined
1015
+ : getSymmetryGroup(config.symmetry, environment, config.substitutions);
740
1016
  if (config.view !== undefined) getConfigOperator("view function", config.view, environment);
741
1017
  const view =
742
1018
  config.view === undefined
@@ -768,14 +1044,12 @@ export const createSearch = (
768
1044
  .sort((left, right) => getTlcPosition(left) - getTlcPosition(right));
769
1045
  return tlcOrder.indices;
770
1046
  };
771
- // A representative in TLC's variable order is the one whose fingerprint TLC reports.
772
- const order = symmetryGroup.length > 0 ? getTlcOrder() : undefined;
773
1047
  const getViewValue = (expression: Expression, state: Value[]) =>
774
1048
  evaluate(expression, getContext(environment, state, undefined));
775
1049
  const getTlcStateFingerprint = (state: Value[]) => {
776
1050
  const indices = getTlcOrder();
777
1051
  const representative =
778
- symmetryGroup.length === 0 ? state : getRepresentative(state, symmetryGroup, indices);
1052
+ symmetryGroup === undefined ? state : getRepresentative(state, symmetryGroup, indices);
779
1053
  return getTlcFingerprint(
780
1054
  view === undefined
781
1055
  ? indices.map((index) => representative[index])
@@ -791,6 +1065,7 @@ export const createSearch = (
791
1065
  const location = range ? ` at ${formatRange(range)}` : "";
792
1066
  return {
793
1067
  name: unwitnessed.name,
1068
+ code: MESSAGE_CODE.possibleUnwitnessed,
794
1069
  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.`,
795
1070
  counts: prettyPrint(formatValue(getPossibleCounts(runtime), true)),
796
1071
  };
@@ -798,7 +1073,8 @@ export const createSearch = (
798
1073
  return {
799
1074
  properties,
800
1075
  spec,
801
- isSymmetric: symmetryGroup.length > 0,
1076
+ isSymmetric: symmetryGroup !== undefined,
1077
+ isConstrained: constraints.length > 0 || actionConstraints.length > 0,
802
1078
  getTlcOrder,
803
1079
  getStoredFingerprints: (states, fingerprintStates) => {
804
1080
  if (view !== undefined || isFingerprintedLikeTlc) {
@@ -814,8 +1090,11 @@ export const createSearch = (
814
1090
  },
815
1091
  getFingerprintState: (state) => {
816
1092
  if (isFingerprintedLikeTlc) return [String(getTlcStateFingerprint(state))];
1093
+ // A representative in TLC's variable order is the one whose fingerprint TLC reports.
817
1094
  const representative =
818
- symmetryGroup.length === 0 ? state : getRepresentative(state, symmetryGroup, order);
1095
+ symmetryGroup === undefined
1096
+ ? state
1097
+ : getRepresentative(state, symmetryGroup, getTlcOrder());
819
1098
  return view === undefined ? representative : [getViewValue(view.expression, representative)];
820
1099
  },
821
1100
  findViolatedInvariant: (state, parent) =>
@@ -831,28 +1110,64 @@ export const createSearch = (
831
1110
  parent[membership.variable],
832
1111
  evaluate(membership.set, context),
833
1112
  )
834
- : !holdsLikeTlc(invariant.expression, context);
1113
+ : !holdsAsConjunct(invariant, context);
835
1114
  } catch (error) {
836
1115
  // TLC reports a failure only on a state after the initial states as an invariant failure.
837
1116
  if (!parent) throw error;
838
1117
  throw withHeadline(
839
1118
  setExitCode(error, EXIT_STATUS.safetyEvaluationFailure),
1119
+ MESSAGE_CODE.invariantEvaluationFailed,
840
1120
  `Evaluating invariant ${invariant.name} failed.`,
841
1121
  );
842
1122
  }
843
1123
  }),
1124
+ checkReplayedInitialState: (state, tracing, addFingerprint) => {
1125
+ const holdsIn = (expression: Expression, scope: Scope | undefined) =>
1126
+ holdsLikeTlc(expression, getContext(tracing, state, undefined, scope));
1127
+ if (constraints.every((constraint) => holdsIn(constraint.predicate, constraint.scope))) {
1128
+ addFingerprint();
1129
+ }
1130
+ const invariant = invariantPredicates.find((check) => !holdsIn(check.predicate, check.scope));
1131
+ if (invariant) return { status: "invariant-violation", name: invariant.name };
1132
+ const predicate = properties.initialPredicates.find(
1133
+ (check) => !holdsIn(check.expression, check.scope),
1134
+ );
1135
+ return predicate && { status: "liveness-violation", name: predicate.name };
1136
+ },
1137
+ checkReplayedSuccessor: (state, next, tracing, addFingerprint) => {
1138
+ // TLC evaluates the action constraints only on a state that satisfies the constraints.
1139
+ const isInModel =
1140
+ constraints.every((constraint) =>
1141
+ holdsLikeTlc(
1142
+ constraint.predicate,
1143
+ getContext(tracing, next, undefined, constraint.scope),
1144
+ ),
1145
+ ) &&
1146
+ actionConstraints.every((constraint) =>
1147
+ holdsLikeTlc(constraint.expression, getContext(tracing, state, next, constraint.scope)),
1148
+ );
1149
+ // ModelChecker.doNext checks the invariants of a successor it has not seen, which includes
1150
+ // one outside the model.
1151
+ const isUnseen = isInModel ? addFingerprint() : true;
1152
+ return (
1153
+ (!isUnseen ||
1154
+ invariantPredicates.every((invariant) =>
1155
+ holdsLikeTlc(
1156
+ invariant.predicate,
1157
+ getContext(tracing, next, undefined, invariant.scope),
1158
+ ),
1159
+ )) &&
1160
+ actionProperties.every((property) =>
1161
+ holdsLikeTlc(property.box, getContext(tracing, state, next, property.scope)),
1162
+ )
1163
+ );
1164
+ },
844
1165
  satisfiesConstraints: (state, parent) =>
845
- constraints.every((constraint) => {
846
- try {
847
- return (
848
- isUnchangedFor(constraint, state, parent) ||
849
- holdsLikeTlc(constraint.expression, getContext(environment, state, undefined))
850
- );
851
- } catch (error) {
852
- // TLC reports a failing constraint on a successor like a failure of the next-state relation.
853
- throw parent ? toNextStateError(error) : error;
854
- }
855
- }),
1166
+ constraints.every(
1167
+ (constraint) =>
1168
+ isUnchangedFor(constraint, state, parent) ||
1169
+ holdsAsConjunct(constraint, getContext(environment, state, undefined)),
1170
+ ),
856
1171
  findFailedInitialPredicate: (state) =>
857
1172
  properties.initialPredicates.find(
858
1173
  (predicate) =>
@@ -880,18 +1195,19 @@ export const createSearch = (
880
1195
  } catch (error) {
881
1196
  throw withHeadline(
882
1197
  withNextStateExitCode(error),
1198
+ MESSAGE_CODE.actionPropertyEvaluationFailed,
883
1199
  `Evaluating action property ${property.name} failed.`,
884
1200
  );
885
1201
  }
886
1202
  }),
887
1203
  satisfiesActionConstraints: (state, next) =>
888
- actionConstraints.every((constraint) => {
889
- try {
890
- return holdsLikeTlc(constraint.expression, getContext(environment, state, next));
891
- } catch (error) {
892
- throw toNextStateError(error);
893
- }
894
- }),
1204
+ actionConstraints.every((constraint) =>
1205
+ holdsLikeTlc(
1206
+ constraint.expression,
1207
+ getContext(environment, state, next),
1208
+ (expression) => `${UNEXPECTED_EXCEPTION}${getExpectedBoolean(expression, environment)}`,
1209
+ ),
1210
+ ),
895
1211
  trackStatePossible:
896
1212
  statePossible.length === 0
897
1213
  ? ignorePossible
@@ -903,14 +1219,40 @@ export const createSearch = (
903
1219
  : (state, next) =>
904
1220
  trackPossible(actionPossible, runtime, getContext(environment, state, next)),
905
1221
  findUnwitnessedPossible,
906
- findPostconditionViolation: () => {
1222
+ findPostconditionViolation: (isAfterViolation = false) => {
1223
+ // TLC replaces a definition it computes when it starts by its value, and then rejects it as
1224
+ // a postcondition before it checks any of them.
1225
+ const constant = config.postconditions.find((name) => {
1226
+ const definition = getDefinition(name, environment);
1227
+ return definition !== undefined && environment.definitionValues.has(definition);
1228
+ });
1229
+ if (constant !== undefined) {
1230
+ if (isAfterViolation) return undefined;
1231
+ throw setExitCode(
1232
+ new TlaEvaluationError(
1233
+ `${UNEXPECTED_EXCEPTION}The post condition ${constant} cannot be a constant.`,
1234
+ ),
1235
+ EXIT_STATUS.error,
1236
+ );
1237
+ }
907
1238
  const unwitnessed = findUnwitnessedPossible();
908
1239
  if (unwitnessed) return unwitnessed;
909
1240
  for (const name of config.postconditions) {
910
1241
  const failure = getConstantFailure(createIdentifier(name), environment, "a postcondition");
911
- if (failure) {
912
- return { name, message: failure.message ?? `Postcondition ${name} is false.` };
913
- }
1242
+ if (!failure) continue;
1243
+ const range = getBodyRange(name, environment);
1244
+ const location = range ? ` at ${formatRange(range)}` : "";
1245
+ return failure.message === undefined
1246
+ ? {
1247
+ name,
1248
+ code: MESSAGE_CODE.postconditionFalse,
1249
+ message: `Postcondition ${name}${location} is false.`,
1250
+ }
1251
+ : {
1252
+ name,
1253
+ code: MESSAGE_CODE.postconditionFailed,
1254
+ message: `Evaluating postcondition ${name}${location} failed.\n${failure.message}`,
1255
+ };
914
1256
  }
915
1257
  return undefined;
916
1258
  },
@@ -922,79 +1264,179 @@ export const createSearch = (
922
1264
  const withNextStateExitCode = (error: unknown) =>
923
1265
  error instanceof TlaModuleError ? setExitCode(error, error.exitCode) : error;
924
1266
 
925
- // TLC reports a failure of the next-state relation as an unexpected exception, unless a standard
926
- // module raised it as an EvalException.
927
- const toNextStateError = (error: unknown) =>
928
- error instanceof TlaEvaluationError &&
929
- !(error instanceof TlaModuleError) &&
930
- !(error instanceof TlaIncompleteStateError)
931
- ? setExitCode(
932
- new TlaEvaluationError(`${UNEXPECTED_EXCEPTION}${error.message}`, error),
933
- getErrorExitCode(error),
934
- )
935
- : withNextStateExitCode(error);
936
-
937
- // TLC keeps the stack only when an evaluation fails, and prints each expression on it once, however
938
- // many times in a row it pushed it.
939
- const getReplayedCallStack = (replay: () => void, trace: Expression[]) => {
1267
+ // Stops a replay where TLC stops it without a failure, as at a violated invariant.
1268
+ const STOP_REPLAY = new Error("The replay stopped");
1269
+
1270
+ // The codes of the errors in the configuration and the spec that TLC's EC.ExitStatus maps to a
1271
+ // configuration error.
1272
+ const CONFIG_ERROR_CODES = new Set([
1273
+ ...Array.from({ length: 24 }, (_, index) => 2222 + index),
1274
+ 2272,
1275
+ 2273,
1276
+ 2274,
1277
+ 2280,
1278
+ 2281,
1279
+ ]);
1280
+
1281
+ // When TLC's replay of the initial states doesn't fail again, it exits with the code of the
1282
+ // TLCRuntimeException it reported.
1283
+ const getInitialExitCode = (error: TlaEvaluationError) => {
1284
+ const coded = getCodedMessage(error.message);
1285
+ return coded && !coded.isEvalException && CONFIG_ERROR_CODES.has(coded.code)
1286
+ ? EXIT_STATUS.configParseError
1287
+ : getErrorExitCode(error);
1288
+ };
1289
+
1290
+ // When TLC's replay of an error fails again, an EvalException from a standard module's Java code
1291
+ // decides the exit status, and any other failure exits as a nested expression failure. An error
1292
+ // that heads or wraps another exits as the other.
1293
+ const getReplayExitCode = (error: TlaEvaluationError): number => {
1294
+ const inner = error.cause;
1295
+ if (inner instanceof TlaEvaluationError) return getReplayExitCode(inner);
1296
+ return error instanceof TlaModuleError ? error.exitCode : EXIT_STATUS.specEvaluationFailure;
1297
+ };
1298
+
1299
+ // An error that TLC reports with a message of its own, by that message's code and first line, and
1300
+ // the error whose message follows.
1301
+ interface HeadedError {
1302
+ code: number;
1303
+ headline: string;
1304
+ inner: TlaEvaluationError;
1305
+ }
1306
+
1307
+ const headedErrors = new WeakMap<Error, HeadedError>();
1308
+
1309
+ const withHeadline = (error: unknown, code: number, headline: string) => {
1310
+ if (!(error instanceof TlaEvaluationError)) return error;
1311
+ const headed = setExitCode(
1312
+ new TlaEvaluationError(`${headline}\n${error.message}`, error),
1313
+ getErrorExitCode(error),
1314
+ );
1315
+ headedErrors.set(headed, { code, headline, inner: error });
1316
+ return headed;
1317
+ };
1318
+
1319
+ const UNEXPECTED_HEADLINE = UNEXPECTED_EXCEPTION.slice(0, UNEXPECTED_EXCEPTION.indexOf("\n"));
1320
+
1321
+ // TLC 1.7.4's Worker wraps an error in adding a successor in a RuntimeException, whose message
1322
+ // names the class of the error.
1323
+ const WRAPPED_EVAL_EXCEPTION = `${UNEXPECTED_EXCEPTION}tlc2.tool.EvalException: `;
1324
+ const WRAPPED_RUNTIME_EXCEPTION = `${UNEXPECTED_EXCEPTION}util.Assert$TLCRuntimeException: `;
1325
+
1326
+ const UNEXPECTED_EVAL_EXCEPTION = getUnexpectedException("tlc2.tool.EvalException");
1327
+
1328
+ const getWrappedException = (error: TlaEvaluationError) =>
1329
+ isEvalException(error) ? WRAPPED_EVAL_EXCEPTION : WRAPPED_RUNTIME_EXCEPTION;
1330
+
1331
+ // TLC reports an EvalException, or a TLCRuntimeException without a message of its own, as an
1332
+ // exception it didn't expect.
1333
+ const withUnexpectedException = <Result>(compute: () => Result) => {
940
1334
  try {
941
- replay();
942
- return undefined;
1335
+ return compute();
943
1336
  } catch (error) {
944
- if (!(error instanceof TlaEvaluationError)) return [];
945
- return trace
946
- .flatMap((expression) => {
947
- const range = expression.location.range;
948
- return range
949
- ? [
950
- `Line ${range.start.line}, column ${range.start.column} to line ${range.end.line}, column ${range.end.column} in ${range.module}`,
951
- ]
952
- : [];
953
- })
954
- .filter((frame, index, frames) => index === 0 || frames[index - 1] !== frame);
1337
+ if (!(error instanceof TlaEvaluationError)) throw error;
1338
+ if (isEvalException(error)) {
1339
+ throw new TlaEvaluationError(`${UNEXPECTED_EVAL_EXCEPTION}${error.message}`);
1340
+ }
1341
+ if (getCodedMessage(error.message)) throw error;
1342
+ throw new TlaEvaluationError(`${UNEXPECTED_EXCEPTION}${error.message}`);
955
1343
  }
956
1344
  };
957
1345
 
958
- const withHeadline = (error: unknown, headline: string) =>
959
- error instanceof TlaEvaluationError
960
- ? setExitCode(
961
- new TlaEvaluationError(`${headline}\n${error.message}`, error),
962
- getErrorExitCode(error),
963
- )
964
- : error;
1346
+ // The starts of TLC's messages for the exceptions it didn't expect.
1347
+ const UNEXPECTED_EXCEPTIONS = [
1348
+ WRAPPED_EVAL_EXCEPTION,
1349
+ WRAPPED_RUNTIME_EXCEPTION,
1350
+ UNEXPECTED_EXCEPTION,
1351
+ UNEXPECTED_EVAL_EXCEPTION,
1352
+ ];
1353
+
1354
+ // The text of an error's message, with the message of a coded error inside it marked in -tool
1355
+ // output as TLC marks it.
1356
+ const formatErrorMessage = (error: TlaEvaluationError, isTool: boolean): string => {
1357
+ const headed = headedErrors.get(error);
1358
+ if (headed) return `${headed.headline}\n${formatErrorMessage(headed.inner, isTool)}`;
1359
+ const message = error.message;
1360
+ const prefix = UNEXPECTED_EXCEPTIONS.find((start) => message.startsWith(start)) ?? "";
1361
+ return `${prefix}${formatNestedMessage(message.slice(prefix.length), isTool)}`;
1362
+ };
1363
+
1364
+ // How TLC reports an error: with the code of its own message for an error that it reports with a
1365
+ // headline; and, when the error escapes the computation of next states, with the code of an
1366
+ // EvalException, or as an unexpected exception for any other error.
1367
+ interface FailureMessage {
1368
+ code: number;
1369
+ message: string;
1370
+ toolMessage: string;
1371
+ }
1372
+
1373
+ const getFailureMessage = (error: TlaEvaluationError, isNextState: boolean): FailureMessage => {
1374
+ const headed = headedErrors.get(error);
1375
+ const message = error.message;
1376
+ if (headed) {
1377
+ return {
1378
+ code: headed.code,
1379
+ message,
1380
+ toolMessage: formatErrorMessage(error, true),
1381
+ };
1382
+ }
1383
+ if (isNextState && isEvalException(error)) {
1384
+ return {
1385
+ code: getCodedMessage(message)?.code ?? MESSAGE_CODE.general,
1386
+ message,
1387
+ toolMessage: message,
1388
+ };
1389
+ }
1390
+ const isUnexpected = isNextState && !message.startsWith(UNEXPECTED_HEADLINE);
1391
+ const prefix = isUnexpected ? UNEXPECTED_EXCEPTION : "";
1392
+ return {
1393
+ code: MESSAGE_CODE.general,
1394
+ message: `${prefix}${message}`,
1395
+ toolMessage: `${prefix}${formatErrorMessage(error, true)}`,
1396
+ };
1397
+ };
965
1398
 
966
1399
  // TLC finishes the -dump file whether or not the search finds a violation.
967
1400
  export const checkSequentially = (options: CheckOptions): CheckResult => {
968
- const stateWriter = options.dump && createStateWriter(options.dump, options.writeFile);
1401
+ const stateWriter =
1402
+ options.dump && createStateWriter(options.dump, options.writeFile, options.version);
969
1403
  try {
970
1404
  return searchStates(options, stateWriter);
971
1405
  } catch (error) {
972
- // TLC reports a stack overflow outside the search as a failure of its own, with exit code 255.
973
- throw isStackOverflow(error)
974
- ? setExitCode(new TlaEvaluationError(STACK_OVERFLOW), EXIT_STATUS.error)
975
- : error;
1406
+ // TLC reports a stack overflow outside the search on its own, and exits with 255.
1407
+ throw isStackOverflow(error) ? createStackOverflowError() : error;
976
1408
  } finally {
977
1409
  stateWriter?.close();
978
1410
  }
979
1411
  };
980
1412
 
1413
+ const createStackOverflowError = () => setExitCode(new TlaStackOverflowError(), EXIT_STATUS.error);
1414
+
981
1415
  const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefined): CheckResult => {
982
- const config = typeof options.config === "string" ? parseConfig(options.config) : options.config;
1416
+ const config =
1417
+ typeof options.config === "string"
1418
+ ? parseConfig(options.config, options.version)
1419
+ : options.config;
983
1420
  const onPrint = options.onPrint ?? console.log;
984
- // TLC prints again while it rebuilds a trace, between the states it prints. Printing those lines
985
- // before the trace would misplace them, so rebuilding a trace prints nothing.
986
- const output = { isMuted: false, replayed: undefined as string[] | undefined };
1421
+ // TLC prints again while it rebuilds a trace, between the states it prints, so rebuilding a trace
1422
+ // keeps what it prints for the trace.
1423
+ const output = { lines: undefined as OutputLine[] | undefined };
987
1424
  const print = (text: string) => {
988
- if (output.replayed) output.replayed.push(text);
989
- else if (!output.isMuted) onPrint(text);
1425
+ if (output.lines) output.lines.push(text);
1426
+ else onPrint(text);
990
1427
  };
991
- const withoutOutput = <Result>(rebuild: () => Result) => {
992
- output.isMuted = true;
993
- const result = rebuild();
994
- output.isMuted = false;
995
- return result;
1428
+ const getOutput = <Result>(rebuild: () => Result) => {
1429
+ const outer = output.lines;
1430
+ const lines: OutputLine[] = [];
1431
+ output.lines = lines;
1432
+ try {
1433
+ return { result: rebuild(), lines };
1434
+ } finally {
1435
+ output.lines = outer;
1436
+ }
996
1437
  };
997
1438
  setStringOrder(getTlcStringOrder(options.source, config, options.loadModule));
1439
+ setValueVersion(options.version);
998
1440
  const specification = createEnvironment(config, {
999
1441
  source: options.source,
1000
1442
  loadModule: options.loadModule,
@@ -1002,9 +1444,16 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1002
1444
  print,
1003
1445
  files: { readFile: options.readFile, writeFile: options.writeFile },
1004
1446
  seed: options.seed,
1447
+ isTool: options.isTool,
1448
+ isTraceRecorded: options.isTraceRecorded,
1449
+ isSanyReported: options.isSanyReported,
1450
+ isWarningEnabled: options.isWarningEnabled,
1451
+ version: options.version,
1005
1452
  });
1453
+ reportStartup(specification, config, options.onProgress);
1006
1454
  const environment = specification.environment;
1007
1455
  const runtime = environment.runtime;
1456
+ const is174 = runtime.version === "1.7.4";
1008
1457
  runtime.pause = options.onPause ?? (() => {});
1009
1458
  runtime.getSpecification = () =>
1010
1459
  getSpecificationValue(
@@ -1013,7 +1462,7 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1013
1462
  specification.variableLocations,
1014
1463
  specification.instanceActions,
1015
1464
  );
1016
- const statistics = { depth: 0 };
1465
+ const statistics = { depth: 0, initialStates: undefined as InitialStates | undefined };
1017
1466
  const createResult = (
1018
1467
  status: CheckStatus,
1019
1468
  violation?: Omit<Violation, "loopStart"> & { loopStart?: number },
@@ -1026,15 +1475,26 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1026
1475
  distinctStates: runtime.distinctStates,
1027
1476
  queuedStates: runtime.queueSize,
1028
1477
  depth: runtime.generatedStates === 0 ? 0 : Math.max(statistics.depth, 1),
1478
+ initialStates: statistics.initialStates,
1029
1479
  outDegrees: undefined,
1030
1480
  fingerprintDistance: undefined,
1031
1481
  });
1032
1482
  const outDegrees = Array.from({ length: OUT_DEGREE_BUCKETS }, () => 0);
1033
1483
  const expansion = { newStates: 0 };
1034
1484
  const getOutDegreeBucket = () => Math.min(expansion.newStates, OUT_DEGREE_BUCKETS - 1);
1035
- // TLC counts the state it was expanding when an evaluation failed.
1485
+ // TLC counts the state it was expanding when an evaluation failed, except TLC 1.7.4, whose
1486
+ // worker stops before it counts the state.
1036
1487
  const getPartialOutDegrees = () =>
1037
1488
  outDegrees.map((count, degree) => (degree === getOutDegreeBucket() ? count + 1 : count));
1489
+ const getFailureOutDegrees = () => (is174 ? [...outDegrees] : getPartialOutDegrees());
1490
+ // TLC 1.7.4 doesn't name the properties a counterexample violates, so it evaluates none of them.
1491
+ const getViolatedProperties = (checker: LivenessChecker, path: Value[][], cycleStart: number) =>
1492
+ is174 ? [] : checker.getViolatedProperties(path, cycleStart);
1493
+ // A violation in a successor ends the expansion of a state before TLC counts it.
1494
+ const withOutDegrees = (result: CheckResult, degrees = [...outDegrees]): CheckResult => ({
1495
+ ...result,
1496
+ violationOutDegrees: degrees,
1497
+ });
1038
1498
  const createSuccess = (): CheckResult => ({
1039
1499
  ...createResult("success"),
1040
1500
  outDegrees: [...outDegrees],
@@ -1048,125 +1508,252 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1048
1508
  ),
1049
1509
  });
1050
1510
 
1051
- const getVariableOrder = () =>
1052
- getTlcDeclarationOrder(options.source, options.loadModule, "variable");
1053
- const search = createSearch(config, environment, getVariableOrder);
1054
- const assumptionViolation = findAssumptionViolation(specification.assumptions, environment);
1055
- if (assumptionViolation) return createResult("assumption-violation", assumptionViolation);
1056
- if (!search) return createSuccess();
1511
+ const search = createSearch(
1512
+ config,
1513
+ environment,
1514
+ () => getTlcVariableOrder(options.source, options.loadModule),
1515
+ options.onProgress,
1516
+ );
1517
+ const findViolatedAssumption = () =>
1518
+ findAssumptionViolation(specification.assumptions, environment);
1519
+ if (!search) {
1520
+ runtime.isStarted = true;
1521
+ const assumptionViolation = findViolatedAssumption();
1522
+ if (assumptionViolation) return createResult("assumption-violation", assumptionViolation);
1523
+ // TLC computes the initial states of a spec without variables, of which there are none.
1524
+ statistics.initialStates = { generated: 0, distinct: 0 };
1525
+ options.onProgress?.({ kind: "initial-states-started" });
1526
+ options.onProgress?.({
1527
+ kind: "initial-states-computed",
1528
+ initialStates: statistics.initialStates,
1529
+ });
1530
+ return createSuccess();
1531
+ }
1057
1532
  const hasPostconditions = config.postconditions.length > 0 || config.possible.length > 0;
1058
- const reportViolation = (
1059
- status: CheckStatus,
1060
- violation: Omit<Violation, "loopStart"> & { loopStart?: number },
1061
- getLoopAction?: () => string | undefined,
1533
+ // The state of each step of a trace without the alias, and the action TLC finds for the step,
1534
+ // which CounterExample records.
1535
+ const traceSteps = new WeakMap<
1536
+ TraceStep,
1537
+ { state: Record<string, Value>; action: SpecAction | undefined }
1538
+ >();
1539
+ const getStepState = (step: TraceStep) => traceSteps.get(step)?.state ?? step.state;
1540
+ const getStepAction = (step: TraceStep) => {
1541
+ const action = traceSteps.get(step)?.action;
1542
+ return action ? toActionValue(action) : createActionRecord(step.action);
1543
+ };
1544
+ // Worker#printTrace checks the postconditions on the CounterExample of each trace it prints, so
1545
+ // what they print follows the trace.
1546
+ const checkTracePostconditions = (
1547
+ trace: TraceStep[],
1548
+ loop: { start: number; action: Value } | undefined,
1062
1549
  ) => {
1063
1550
  if (hasPostconditions) {
1064
- const start = violation.loopStart;
1065
1551
  runtime.counterExample = createCounterExample(
1066
- violation.trace,
1067
- start === undefined || !getLoopAction ? undefined : { start, action: getLoopAction() },
1552
+ trace.map(getStepState),
1553
+ trace.slice(1).map(getStepAction),
1554
+ loop,
1068
1555
  );
1069
1556
  }
1070
1557
  const unwitnessed = search.findUnwitnessedPossible();
1071
- if (!unwitnessed) search.findPostconditionViolation();
1072
- return createResult(status, unwitnessed ? { ...violation, unwitnessed } : violation);
1558
+ const checked = unwitnessed
1559
+ ? { result: undefined, lines: [] }
1560
+ : getOutput(() => search.findPostconditionViolation(true));
1561
+ return { unwitnessed, postcondition: checked.result, lines: checked.lines };
1562
+ };
1563
+ const reportViolation = (
1564
+ status: CheckStatus,
1565
+ violation: Omit<Violation, "loopStart"> & { loopStart?: number },
1566
+ getLoopAction?: () => Value,
1567
+ ) => {
1568
+ const start = violation.loopStart;
1569
+ const checked = checkTracePostconditions(
1570
+ violation.trace,
1571
+ start === undefined || !getLoopAction ? undefined : { start, action: getLoopAction() },
1572
+ );
1573
+ const traceOutput = [...(violation.traceOutput ?? []), ...checked.lines];
1574
+ return createResult(status, {
1575
+ ...violation,
1576
+ ...(traceOutput.length > 0 && { traceOutput }),
1577
+ ...(checked.unwitnessed && { unwitnessed: checked.unwitnessed }),
1578
+ ...(checked.postcondition && { postcondition: checked.postcondition }),
1579
+ });
1073
1580
  };
1074
1581
  const spec = search.spec;
1075
1582
  const getFingerprintState = search.getFingerprintState;
1076
1583
  const nextActions = { value: undefined as SpecAction[] | undefined };
1077
- const replayFailure = (
1078
- result: CheckResult,
1079
- replay: (tracedSearch: Search, traced: Environment) => void,
1080
- ): CheckResult => {
1081
- if (!result.failure) return result;
1082
- const trace: Expression[] = [];
1083
- const traced: Environment = { ...environment, evaluators: new WeakMap(), trace };
1084
- const tracedSearch = createSearch(config, traced, getVariableOrder);
1085
- if (!tracedSearch) return result;
1086
- const replayed: string[] = [];
1087
- output.replayed = replayed;
1088
- const callStack = getReplayedCallStack(() => replay(tracedSearch, traced), trace);
1089
- output.replayed = undefined;
1090
- return { ...result, failure: { ...result.failure, replay: { output: replayed, callStack } } };
1584
+ const getSpecNextActions = () =>
1585
+ (nextActions.value ??= getNextActions(config, environment, specification.instanceActions));
1586
+ // Where TLC's replay of a failed computation fails, or undefined when the replay completes.
1587
+ const getReplayFailure = (replay: (tracing: Environment) => void): ReplayFailure | undefined => {
1588
+ const tracing = createTracingEnvironment(environment);
1589
+ const callStack = tracing.callStack;
1590
+ try {
1591
+ replay(tracing);
1592
+ return undefined;
1593
+ } catch (error) {
1594
+ // A replay that overflows the stack again has an empty call stack.
1595
+ if (isStackOverflow(error)) return { callStack: [], fingerprint: undefined };
1596
+ if (!(error instanceof TlaEvaluationError) || !callStack) return undefined;
1597
+ return { callStack: callStack.expressions, fingerprint: callStack.fingerprint };
1598
+ }
1091
1599
  };
1092
- // TLC checks every initial state again, as when it first generated them.
1093
- const replayInitialStates = (result: CheckResult) =>
1094
- replayFailure(result, (tracedSearch, traced) => {
1095
- if (spec.init === undefined) return;
1096
- forEachInitialState(
1097
- spec.init,
1098
- traced,
1600
+ // The sources of the values a fingerprint fails inside, outermost first: each value fails as it
1601
+ // fingerprints a value it holds.
1602
+ const findFailedSources = (value: Value, sources: CallStack["sources"]): Expression[] => {
1603
+ if (typeof value !== "object") return [];
1604
+ const source = sources.get(value);
1605
+ const failed = getHeldValues(value).find((held) => getFingerprintError(held) !== undefined);
1606
+ return [
1607
+ ...(source ? [source] : []),
1608
+ ...(failed === undefined ? [] : findFailedSources(failed, sources)),
1609
+ ];
1610
+ };
1611
+ // TLC's replay fingerprints the states it finds, and a value the replay built raises a
1612
+ // FingerprintException when it fails to.
1613
+ const fingerprintReplayed = (state: Value[], callStack: CallStack | undefined) => {
1614
+ for (const value of getFingerprintState(state)) {
1615
+ const error = getFingerprintError(value);
1616
+ if (!error) continue;
1617
+ const sources = callStack ? findFailedSources(value, callStack.sources) : [];
1618
+ // TLC fingerprints a state outside any evaluation, so its call stack is empty.
1619
+ if (callStack && sources.length > 0) {
1620
+ callStack.expressions.length = 0;
1621
+ callStack.isFrozen = true;
1622
+ callStack.fingerprint = { sources, reason: error.message };
1623
+ }
1624
+ throw error;
1625
+ }
1626
+ state.forEach(markFingerprinted);
1627
+ };
1628
+ // The replay adds the states it hasn't seen to TLC's set of states, which already holds the state
1629
+ // that failed after TLC added it.
1630
+ const createReplayedStates = () => {
1631
+ const replayed = unstoredState.fingerprint ? [unstoredState.fingerprint] : [];
1632
+ return (state: Value[], callStack: CallStack | undefined) => {
1633
+ fingerprintReplayed(state, callStack);
1634
+ const fingerprintState = getFingerprintState(state);
1635
+ const isSeen =
1636
+ findStateIndex(getStateHash(fingerprintState), fingerprintState) !== -1 ||
1637
+ replayed.some((seen) => isSameState(seen, fingerprintState));
1638
+ if (isSeen) return false;
1639
+ replayed.push(fingerprintState);
1640
+ runtime.distinctStates++;
1641
+ return true;
1642
+ };
1643
+ };
1644
+ // TLC's DoInitFunctor reports its progress again as it replays the initial states, and adds each
1645
+ // one it hasn't seen to the behavior graph. After a FingerprintException, it only counts the
1646
+ // states left, then throws the exception.
1647
+ const replayInit = () => {
1648
+ const replayed = { count: 0 };
1649
+ const deferred: TlaEvaluationError[] = [];
1650
+ const addReplayed = createReplayedStates();
1651
+ return getReplayFailure((tracing) => {
1652
+ replayInitialStates(
1653
+ getInitActions(config, environment, specification.instanceActions),
1654
+ tracing,
1099
1655
  (state) => {
1100
- tracedSearch.satisfiesConstraints(state);
1101
- return (
1102
- tracedSearch.findViolatedInvariant(state) !== undefined ||
1103
- tracedSearch.findFailedInitialPredicate(state) !== undefined
1104
- );
1656
+ reportInitialStatesProgress(replayed.count, (progress) => output.lines?.push(progress));
1657
+ replayed.count++;
1658
+ runtime.generatedStates = replayed.count;
1659
+ if (deferred.length > 0) return;
1660
+ try {
1661
+ const addFingerprint = () => {
1662
+ if (!addReplayed(state, tracing.callStack)) return;
1663
+ runtime.queueSize++;
1664
+ liveness?.addInitialState(states.length, state, tracing);
1665
+ };
1666
+ const violation = search.checkReplayedInitialState(state, tracing, addFingerprint);
1667
+ if (violation) {
1668
+ const traced = toTrace([{ action: undefined, state }], []).trace[0].state;
1669
+ output.lines?.push({ kind: "initial-state-violation", ...violation, state: traced });
1670
+ throw STOP_REPLAY;
1671
+ }
1672
+ } catch (error) {
1673
+ if (!(error instanceof TlaEvaluationError) || !tracing.callStack?.fingerprint) {
1674
+ throw error;
1675
+ }
1676
+ deferred.push(error);
1677
+ }
1105
1678
  },
1106
- spec.scope,
1107
1679
  );
1680
+ if (deferred.length > 0) throw deferred[0];
1108
1681
  });
1109
- // TLC rebuilds the behavior up to the state it expanded before it replays the step.
1110
- const rebuildBehavior = (index: number): void => {
1111
- const parent = parents[index];
1112
- if (parent === -1) {
1113
- getSpecInitialStates();
1114
- return;
1115
- }
1116
- rebuildBehavior(parent);
1117
- getLabel(parent, states[parent], states[index]);
1118
1682
  };
1119
- // TLC generates the successors of each action before it checks them. It checks the invariants
1120
- // only of a successor outside the model, since it has seen the others.
1121
- const replaySuccessors = (result: CheckResult, index: number) =>
1122
- replayFailure(result, (tracedSearch, traced) => {
1123
- rebuildBehavior(index);
1683
+ // TLC replays the expansion of a state with ModelChecker.doNext, which writes each successor in
1684
+ // the model to the -dump state graph again.
1685
+ const replayNext = (index: number) =>
1686
+ getReplayFailure((tracing) => {
1124
1687
  const state = states[index];
1125
- nextActions.value ??= getNextActions(config, environment, specification.instanceActions);
1126
- nextActions.value.find((action) =>
1127
- getSuccessors(action.expression, state, traced, action.scope).some((successor) => {
1128
- const isInModel =
1129
- tracedSearch.satisfiesConstraints(successor.state) &&
1130
- tracedSearch.satisfiesActionConstraints(state, successor.state);
1131
- return (
1132
- (!isInModel && tracedSearch.findViolatedInvariant(successor.state) !== undefined) ||
1133
- tracedSearch.findViolatedActionProperty(state, successor.state) !== undefined
1134
- );
1135
- }),
1136
- );
1688
+ const source = stateWriter && getGraphState(state, depths[index]);
1689
+ const addReplayed = createReplayedStates();
1690
+ replaySuccessors(getSpecNextActions(), state, tracing, (next, action) => {
1691
+ const addFingerprint = () => {
1692
+ const isUnseen = addReplayed(next, tracing.callStack);
1693
+ if (source) {
1694
+ stateWriter?.writeSuccessor(
1695
+ source,
1696
+ getGraphState(next, depths[index] + 1),
1697
+ !isUnseen,
1698
+ isNamingEdges
1699
+ ? { name: action.name, signature: getActionSignature(action) }
1700
+ : undefined,
1701
+ );
1702
+ }
1703
+ return isUnseen;
1704
+ };
1705
+ if (!search.checkReplayedSuccessor(state, next, tracing, addFingerprint)) {
1706
+ throw STOP_REPLAY;
1707
+ }
1708
+ });
1137
1709
  });
1138
1710
  const isReducing = config.view !== undefined || config.symmetry !== undefined;
1139
1711
  const tlcFingerprints: number[] = [];
1712
+ // TLC warns about the liveness checker before it builds it.
1713
+ if (search.properties.liveness.length > 0) {
1714
+ options.onProgress?.({
1715
+ kind: "liveness-initializing",
1716
+ isSymmetric: search.isSymmetric,
1717
+ isConstrained: search.isConstrained,
1718
+ });
1719
+ }
1140
1720
  const liveness = withLivenessExitCode(() =>
1141
- createLivenessChecker(search.properties.liveness, spec.temporals, environment, {
1142
- getFingerprint: (index) =>
1143
- (tlcFingerprints[index] ??= Number(
1144
- BigInt.asIntN(32, runtime.getFingerprint(states[index])),
1145
- )),
1146
- getSuccessors: (state) => {
1147
- const successors: LiveSuccessor[] = [];
1148
- if (spec.next === undefined) return successors;
1149
- forEachSuccessor(
1150
- spec.next,
1151
- state,
1152
- environment,
1153
- (successor) => {
1154
- canonicalizeState(successor.state);
1155
- const isInModel =
1156
- search.satisfiesConstraints(successor.state, state) &&
1157
- search.satisfiesActionConstraints(state, successor.state);
1158
- if (!isInModel) return false;
1159
- const fingerprintState = getFingerprintState(successor.state);
1160
- const index = findStateIndex(getStateHash(fingerprintState), fingerprintState);
1161
- successors.push({ index, state: successor.state });
1162
- return false;
1163
- },
1164
- spec.scope,
1165
- );
1166
- return successors;
1167
- },
1168
- }),
1721
+ withUnexpectedException(() =>
1722
+ createLivenessChecker(search.properties.liveness, spec.temporals, environment, {
1723
+ getFingerprint: ({ index, state }) =>
1724
+ (tlcFingerprints[index] ??= Number(BigInt.asIntN(32, runtime.getFingerprint(state)))),
1725
+ getSuccessors: (source, state) => {
1726
+ const successors: LiveSuccessor[] = [];
1727
+ if (spec.next === undefined) return successors;
1728
+ // The constraints read the level of the state whose successors they check, as when TLC
1729
+ // explored it.
1730
+ const livenessSource = current.livenessSource;
1731
+ current.livenessSource = source;
1732
+ forEachSuccessor(
1733
+ spec.next,
1734
+ state,
1735
+ environment,
1736
+ (successor) => {
1737
+ canonicalizeState(successor.state);
1738
+ const isInModel =
1739
+ search.satisfiesConstraints(successor.state, state) &&
1740
+ search.satisfiesActionConstraints(state, successor.state);
1741
+ if (!isInModel) return false;
1742
+ const fingerprintState = getFingerprintState(successor.state);
1743
+ const index = findStateIndex(getStateHash(fingerprintState), fingerprintState);
1744
+ successors.push({ index, state: successor.state });
1745
+ return false;
1746
+ },
1747
+ spec.scope,
1748
+ );
1749
+ current.livenessSource = livenessSource;
1750
+ return successors;
1751
+ },
1752
+ }),
1753
+ ),
1169
1754
  );
1755
+ // TLC 1.7.4 creates its model checker, which TLCGet reads, once it has built the liveness checker.
1756
+ runtime.isStarted = true;
1170
1757
  const isCanonicalizedFirst = search.isSymmetric || liveness !== undefined;
1171
1758
 
1172
1759
  const states: Value[][] = [];
@@ -1206,58 +1793,107 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1206
1793
  return toAliasRecord(value, fieldOrder) ?? toRecord(state);
1207
1794
  } catch (error) {
1208
1795
  if (!(error instanceof TlaConfigError || error instanceof TlaEvaluationError)) throw error;
1209
- return { ...toRecord(state), _ALIASEvalError: error.message };
1796
+ return {
1797
+ ...toRecord(state),
1798
+ _ALIASEvalError: formatNestedMessage(error.message, options.isTool ?? false),
1799
+ };
1210
1800
  }
1211
1801
  };
1212
- // TLC labels a step with the first action that takes it, evaluated as when the search expanded
1213
- // the previous state.
1214
- const getLabel = (index: number, previous: Value[], state: Value[]) => {
1215
- nextActions.value ??= getNextActions(config, environment, specification.instanceActions);
1802
+ // TLC finds the action of a step as the first action that takes it, evaluated as when the search
1803
+ // expanded the previous state.
1804
+ // TLC finds the action of a successor it holds by the successor's values, and of any other state
1805
+ // by its fingerprint.
1806
+ const findStepAction = (index: number, previous: Value[], state: Value[], isHeld: boolean) => {
1807
+ const actions = getSpecNextActions();
1216
1808
  const expanding = { ...current };
1217
1809
  Object.assign(current, { index, isExpanding: true, candidate: undefined });
1218
- const fingerprintState = getFingerprintState(state);
1219
- const action = nextActions.value.find((item) =>
1810
+ const getKey = isHeld ? (values: Value[]) => values : getFingerprintState;
1811
+ const key = getKey(state);
1812
+ const action = actions.find((item) =>
1220
1813
  getSuccessors(item.expression, previous, environment, item.scope).some((successor) =>
1221
- isSameState(getFingerprintState(successor.state), fingerprintState),
1814
+ isSameState(getKey(successor.state), key),
1222
1815
  ),
1223
1816
  );
1224
1817
  Object.assign(current, expanding);
1225
- return action && getActionLabel(action);
1818
+ return action;
1226
1819
  };
1227
- const toTrace = (steps: Successor[], path: number[], loopStart?: number): TraceStep[] => {
1820
+ // Before TLC prints a trace, it rebuilds from the initial predicate the states it does not keep,
1821
+ // all but the last `known` ones. As it prints each later step, it finds the action that takes
1822
+ // the step. Then it rebuilds the trace once more, unless the trace is a liveness counterexample
1823
+ // or TLC is 1.7.4.
1824
+ const toTrace = (
1825
+ steps: Successor[],
1826
+ path: number[],
1827
+ traceOptions: TraceOptions = {},
1828
+ ): Behavior => {
1228
1829
  const alias = config.alias;
1229
- const labels = withoutOutput(() => {
1230
- // TLC rebuilds a trace from the initial predicate, which can reset what TLCSet stored.
1231
- if (steps.length > 1 && isImpure(environment)) getSpecInitialStates();
1232
- // TLC finds the action that takes each step before it evaluates the alias.
1233
- return steps.map((step, position) =>
1234
- position === 0 || step.action === "Stuttering"
1235
- ? undefined
1236
- : getLabel(path[position - 1], steps[position - 1].state, step.state),
1237
- );
1238
- });
1239
- return steps.map((step, position) => ({
1240
- action: step.action,
1241
- label: labels[position],
1242
- state:
1243
- alias === undefined
1244
- ? toRecord(step.state)
1245
- : getAliasState(alias, steps, position, loopStart),
1246
- }));
1830
+ const known = traceOptions.known ?? 1;
1831
+ // Rebuilding the trace from the initial predicate can reset what TLCSet stored.
1832
+ const initialOutput = steps.length > 1 ? getOutput(getSpecInitialStates).lines : [];
1833
+ // TLC finds the action that takes each step before it evaluates the alias.
1834
+ const found = steps.map((step, position) =>
1835
+ position === 0 || step.action === "Stuttering"
1836
+ ? { result: undefined, lines: [] }
1837
+ : getOutput(() =>
1838
+ findStepAction(
1839
+ path[position - 1],
1840
+ steps[position - 1].state,
1841
+ step.state,
1842
+ known === 2 && position === steps.length - 1,
1843
+ ),
1844
+ ),
1845
+ );
1846
+ const outputs = found.map((step) => step.lines);
1847
+ const loopStart = traceOptions.loopStart;
1848
+ // 1.7.4's LiveWorker#printTrace rebuilds a lasso up to the start of its cycle at once, and then
1849
+ // each state of the cycle as it prints it.
1850
+ const rebuilt = is174 && loopStart !== undefined ? loopStart + 1 : steps.length - known;
1851
+ const prefixOutput = rebuilt > 0 ? [initialOutput, ...outputs.slice(1, rebuilt)].flat() : [];
1852
+ return {
1853
+ trace: steps.map((step, position) => {
1854
+ const action = found[position].result;
1855
+ const traceStep: TraceStep = {
1856
+ action: step.action,
1857
+ label: action && getActionLabel(action, options.version),
1858
+ state:
1859
+ alias === undefined
1860
+ ? toRecord(step.state)
1861
+ : getAliasState(alias, steps, position, loopStart),
1862
+ output: position === 0 ? prefixOutput : position < rebuilt ? [] : outputs[position],
1863
+ };
1864
+ if (alias !== undefined || action) {
1865
+ traceSteps.set(traceStep, { state: toRecord(step.state), action });
1866
+ }
1867
+ return traceStep;
1868
+ }),
1869
+ traceOutput: known > 0 && !is174 ? [initialOutput, ...outputs].flat() : [],
1870
+ };
1247
1871
  };
1248
1872
  const getSpecInitialStates = () =>
1249
1873
  spec.init === undefined ? [] : getInitialStates(spec.init, environment, spec.scope);
1250
- const getTraceSuccessors = (state: Value[]) =>
1251
- spec.next === undefined ? [] : getSuccessors(spec.next, state, environment, spec.scope);
1874
+ // TLC's Tool#getState rebuilds a successor action by action, up to the first action that
1875
+ // generates it. A trace keeps what the spec prints as TLC rebuilds it, so finding its states
1876
+ // prints nothing.
1877
+ const findTraceSuccessor = (state: Value[], isMatch: (successor: Successor) => boolean) =>
1878
+ getOutput(() => {
1879
+ for (const action of getSpecNextActions()) {
1880
+ const successor = getSuccessors(action.expression, state, environment, action.scope).find(
1881
+ isMatch,
1882
+ );
1883
+ if (successor) return { ...successor, action: successor.action ?? action.name };
1884
+ }
1885
+ return undefined;
1886
+ }).result;
1252
1887
  const hasFingerprint = (state: Value[], index: number) =>
1253
1888
  isSameState(getFingerprintState(state), fingerprintStates[index]);
1254
1889
  const findSuccessorWithFingerprint = (state: Value[], index: number) =>
1255
- getTraceSuccessors(state).find((successor) => hasFingerprint(successor.state, index));
1890
+ findTraceSuccessor(state, (successor) => hasFingerprint(successor.state, index));
1256
1891
  const getPathStates = (path: number[], nextFailure: string) => {
1257
- const initial =
1892
+ const initial = getOutput(() =>
1258
1893
  isReducing || isImpure(environment)
1259
1894
  ? getSpecInitialStates().find((state) => hasFingerprint(state, path[0]))
1260
- : states[path[0]];
1895
+ : states[path[0]],
1896
+ ).result;
1261
1897
  if (!initial) throw new TlaEvaluationError(INITIAL_RECOVERY_FAILURE);
1262
1898
  const steps: Successor[] = [{ state: initial, action: undefined }];
1263
1899
  for (let position = 1; position < path.length; position++) {
@@ -1283,46 +1919,119 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1283
1919
  : path.map((position) => ({ state: states[position], action: actions[position] }));
1284
1920
  if (!last) return toTrace(steps, path);
1285
1921
  const action = isReducing
1286
- ? getTraceSuccessors(states[index]).find((successor) =>
1287
- isSameState(successor.state, last.state),
1288
- )?.action
1922
+ ? findTraceSuccessor(states[index], (successor) => isSameState(successor.state, last.state))
1923
+ ?.action
1289
1924
  : last.action;
1290
- return toTrace([...steps, { state: last.state, action }], path);
1925
+ return toTrace([...steps, { state: last.state, action }], path, { known: 2 });
1291
1926
  };
1292
1927
  // TLC prints an initial state on its own without evaluating the alias.
1293
- const getStateTrace = (index: number) =>
1928
+ // TLCTrace#getTrace recovers even a lone initial state from the initial predicate, printing
1929
+ // again, though TLC 1.7.4 doesn't.
1930
+ const getStateTrace = (index: number): Behavior =>
1294
1931
  parents[index] === -1
1295
- ? [{ action: undefined, label: undefined, state: toRecord(states[index]) }]
1932
+ ? {
1933
+ trace: [{ action: undefined, label: undefined, state: toRecord(states[index]) }],
1934
+ traceOutput: is174 ? [] : getOutput(getSpecInitialStates).lines,
1935
+ }
1296
1936
  : getTrace(index);
1937
+ // TLC rebuilds the trace again for the postcondition after it prints a violation, but not after
1938
+ // an evaluation fails.
1939
+ const getFailedTrace = (index: number, successor: Successor): Behavior => ({
1940
+ trace: getTrace(index, successor).trace,
1941
+ });
1297
1942
  // TLC names the initial state it was checking unless a standard module's Java code failed.
1298
- const toFailure = (
1299
- error: unknown,
1300
- trace: TraceStep[],
1301
- initialState?: Value[],
1302
- failureOutDegrees?: number[],
1303
- ): CheckResult => {
1304
- // TLC exits with 255 on a stack overflow while it computes next states, and prints the
1305
- // behavior up to the state it was expanding.
1306
- if (isStackOverflow(error)) {
1307
- return current.isExpanding
1308
- ? toFailure(
1309
- setExitCode(new TlaEvaluationError(STACK_OVERFLOW), EXIT_STATUS.error),
1310
- getStateTrace(current.index),
1311
- )
1312
- : toFailure(new TlaEvaluationError(STACK_OVERFLOW), trace, initialState);
1943
+ const getFailureExitCode = (error: TlaEvaluationError, failureOptions: FailureOptions) => {
1944
+ // TLC 1.7.4 exits with the result of its replay of the initial states, which only fails again
1945
+ // when the error isn't in adding a state it has already seen to the behavior graph.
1946
+ if (
1947
+ failureOptions.isInitial &&
1948
+ !failureOptions.callStack &&
1949
+ !failureOptions.fingerprint &&
1950
+ is174
1951
+ ) {
1952
+ return EXIT_STATUS.success;
1953
+ }
1954
+ if (!failureOptions.callStack) {
1955
+ return failureOptions.isInitial ? getInitialExitCode(error) : getErrorExitCode(error);
1956
+ }
1957
+ if (failureOptions.isCallStackFirst) return getErrorExitCode(error);
1958
+ // Without a replay, TLC exits with the code of the error, as for any error it didn't expect.
1959
+ if (failureOptions.isLiveCallStack) {
1960
+ return (
1961
+ getExitCode(error) ?? (error instanceof TlaModuleError ? error.exitCode : EXIT_STATUS.error)
1962
+ );
1313
1963
  }
1964
+ // TLC exits with the code of a failed replay of the initial states regardless of the error, as
1965
+ // it does for a replay that fails to fingerprint.
1966
+ return failureOptions.isInitial || failureOptions.fingerprint
1967
+ ? EXIT_STATUS.specEvaluationFailure
1968
+ : getReplayExitCode(error);
1969
+ };
1970
+ const toFailure = (failed: unknown, behavior: Behavior, failureOptions: FailureOptions = {}) => {
1971
+ const error = isStackOverflow(failed) ? new TlaStackOverflowError() : failed;
1314
1972
  if (!(error instanceof TlaEvaluationError)) throw error;
1973
+ const checked =
1974
+ behavior.trace.length > 0 && !failureOptions.traceFailure
1975
+ ? checkTracePostconditions(behavior.trace, undefined)
1976
+ : undefined;
1977
+ const postcondition = checked?.unwitnessed ?? checked?.postcondition;
1978
+ const traceOutput = [...(behavior.traceOutput ?? []), ...(checked?.lines ?? [])];
1315
1979
  return {
1316
1980
  ...createResult("error", undefined, {
1317
- message: error.message,
1318
- trace,
1981
+ ...getFailureMessage(error, failureOptions.isNextState ?? false),
1982
+ ...behavior,
1983
+ ...(traceOutput.length > 0 && { traceOutput }),
1984
+ ...(postcondition && { postcondition }),
1319
1985
  initialState:
1320
- initialState && !(error instanceof TlaModuleError) ? toRecord(initialState) : undefined,
1321
- exitCode: getErrorExitCode(error),
1986
+ failureOptions.initialState && !(error instanceof TlaModuleError)
1987
+ ? toRecord(failureOptions.initialState)
1988
+ : undefined,
1989
+ exitCode: getFailureExitCode(error, failureOptions),
1990
+ callStack: failureOptions.callStack,
1991
+ ...(failureOptions.isCallStackFirst && { isCallStackFirst: true }),
1992
+ ...(failureOptions.fingerprint && { fingerprint: failureOptions.fingerprint }),
1993
+ ...(failureOptions.traceFailure && { traceFailure: failureOptions.traceFailure }),
1322
1994
  }),
1323
- outDegrees: failureOutDegrees,
1995
+ outDegrees: failureOptions.outDegrees,
1324
1996
  };
1325
1997
  };
1998
+ // TLC reports a successor state that an action leaves incomplete with the trace to it, which ends
1999
+ // with the partial state. It names the action when the next-state relation has several.
2000
+ const reportIncompleteSuccessor = (index: number, error: TlaIncompleteSuccessorError) => {
2001
+ runtime.generatedStates++;
2002
+ const actions = getSpecNextActions();
2003
+ const action =
2004
+ actions.length === 1 ? actions[0] : actions.find((item) => item.name === error.action);
2005
+ const missing = error.variables;
2006
+ const subject =
2007
+ actions.length === 1
2008
+ ? "the next-state action"
2009
+ : `action ${error.action} of the next-state relation`;
2010
+ // TLC 1.7.4 says a variable is not assigned rather than not defined.
2011
+ const verb = is174 ? "assigned" : "defined";
2012
+ const message = `Successor state is not completely specified by ${subject}. The following variable${missing.length > 1 ? "s are" : " is"} not ${verb}: ${missing.join(", ")}.\n`;
2013
+ const undefinedValue = createModelValue("null");
2014
+ const partial = error.state.map((value) => value ?? undefinedValue);
2015
+ const failure = toFailure(error, getStateTrace(index));
2016
+ return withOutDegrees({
2017
+ ...failure,
2018
+ failure: failure.failure && {
2019
+ ...failure.failure,
2020
+ code: MESSAGE_CODE.incompleteSuccessor,
2021
+ message,
2022
+ toolMessage: message,
2023
+ exitCode: EXIT_STATUS.specEvaluationFailure,
2024
+ trace: [
2025
+ ...failure.failure.trace,
2026
+ {
2027
+ action: error.action,
2028
+ label: action && getActionLabel(action, options.version),
2029
+ state: toRecord(partial),
2030
+ },
2031
+ ],
2032
+ },
2033
+ });
2034
+ };
1326
2035
  const getPathSteps = (path: number[], loopStart?: number) => {
1327
2036
  const steps = getPathStates(path, NEXT_RECOVERY_FAILURE);
1328
2037
  const last = steps[steps.length - 1].state;
@@ -1340,6 +2049,13 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1340
2049
  hash = combineHash(hash, getValueHash(state[index]));
1341
2050
  return hash & 0x3fffffff;
1342
2051
  };
2052
+ // TLC fingerprints a state once it finds the state in the model.
2053
+ const fingerprintModelState = (state: Value[]) => {
2054
+ for (const value of state) {
2055
+ const error = getFingerprintError(value);
2056
+ if (error) throw error;
2057
+ }
2058
+ };
1343
2059
  const isSameState = (stored: Value[], state: Value[]) => {
1344
2060
  for (let position = 0; position < state.length; position++) {
1345
2061
  if (!isSameValue(stored[position], state[position])) return false;
@@ -1376,6 +2092,9 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1376
2092
  }
1377
2093
  insertSeen(hash, index + 1);
1378
2094
  };
2095
+ // A new successor that TLC has added to its set of states before it checks the successor, which
2096
+ // the check stores after.
2097
+ const unstoredState = { fingerprint: undefined as Value[] | undefined };
1379
2098
  const countDistinctState = (depth: number) => {
1380
2099
  runtime.distinctStates = states.length + 1;
1381
2100
  statistics.depth = Math.max(statistics.depth, depth);
@@ -1400,7 +2119,6 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1400
2119
  isExpanding: false,
1401
2120
  candidate: undefined as Value[] | undefined,
1402
2121
  candidateLevel: 0,
1403
- isFingerprinting: false,
1404
2122
  livenessSource: -1,
1405
2123
  };
1406
2124
  const getPath = (index: number): Value[][] =>
@@ -1419,6 +2137,11 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1419
2137
  };
1420
2138
  runtime.getLevel = (state) => {
1421
2139
  const source = current.livenessSource;
2140
+ // TLC 1.7.4 reads the level of the state its worker explores, whichever state it evaluates.
2141
+ if (is174) {
2142
+ const explored = source !== -1 ? source : current.isExpanding ? current.index : -1;
2143
+ return explored === -1 ? 0 : depths[explored];
2144
+ }
1422
2145
  if (source !== -1) return state === states[source] ? depths[source] : depths[source] + 1;
1423
2146
  if (state === current.candidate) return current.candidateLevel;
1424
2147
  if (current.index === -1) return 0;
@@ -1447,9 +2170,14 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1447
2170
  const fingerprintState = getFingerprintState(state);
1448
2171
  const hash = getStateHash(fingerprintState);
1449
2172
  const isInModel = search.satisfiesConstraints(state);
1450
- if (isInModel) search.trackStatePossible(state);
2173
+ if (isInModel) {
2174
+ search.trackStatePossible(state);
2175
+ fingerprintModelState(fingerprintState);
2176
+ state.forEach(markFingerprinted);
2177
+ }
1451
2178
  const isSeen = isInModel && findStateIndex(hash, fingerprintState) !== -1;
1452
2179
  if (isSeen) return undefined;
2180
+ unstoredState.fingerprint = isInModel ? fingerprintState : undefined;
1453
2181
  if (isInModel) {
1454
2182
  countDistinctState(1);
1455
2183
  runtime.queueSize++;
@@ -1460,14 +2188,14 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1460
2188
  if (violated) {
1461
2189
  return reportViolation("invariant-violation", {
1462
2190
  name: violated.name,
1463
- trace: toTrace([{ action: undefined, state }], []),
2191
+ ...toTrace([{ action: undefined, state }], []),
1464
2192
  });
1465
2193
  }
1466
2194
  const failedPredicate = search.findFailedInitialPredicate(state);
1467
2195
  if (failedPredicate) {
1468
2196
  return reportViolation("liveness-violation", {
1469
2197
  name: failedPredicate.name,
1470
- trace: toTrace([{ action: undefined, state }], []),
2198
+ ...toTrace([{ action: undefined, state }], []),
1471
2199
  });
1472
2200
  }
1473
2201
  if (!isInModel) return undefined;
@@ -1487,15 +2215,17 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1487
2215
  current.candidate = successor.state;
1488
2216
  current.candidateLevel = depths[index] + 1;
1489
2217
  if (isCanonicalizedFirst) canonicalizeState(successor.state);
1490
- current.isFingerprinting = true;
1491
2218
  const fingerprintState = getFingerprintState(successor.state);
1492
2219
  const hash = getStateHash(fingerprintState);
1493
- current.isFingerprinting = false;
1494
2220
  const found = findStateIndex(hash, fingerprintState);
1495
2221
  const isStateInModel = search.satisfiesConstraints(successor.state, state);
1496
2222
  if (isStateInModel) search.trackStatePossible(successor.state);
1497
2223
  const isInModel = isStateInModel && search.satisfiesActionConstraints(state, successor.state);
1498
- if (isInModel) search.trackActionPossible(state, successor.state);
2224
+ if (isInModel) {
2225
+ search.trackActionPossible(state, successor.state);
2226
+ fingerprintModelState(fingerprintState);
2227
+ successor.state.forEach(markFingerprinted);
2228
+ }
1499
2229
  const existing = isInModel ? found : -1;
1500
2230
  if (source && isInModel) {
1501
2231
  stateWriter?.writeSuccessor(
@@ -1511,6 +2241,9 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1511
2241
  liveSuccessors.push({ index: existing, state: isStored ? stored : successor.state });
1512
2242
  }
1513
2243
  const isNew = isInModel && existing === -1;
2244
+ // TLC adds a new state to the behavior graph's successors before it checks the invariants.
2245
+ if (isNew && liveness) liveSuccessors.push({ index: states.length, state: successor.state });
2246
+ unstoredState.fingerprint = isNew ? fingerprintState : undefined;
1514
2247
  if (isNew) {
1515
2248
  countDistinctState(depths[index] + 1);
1516
2249
  expansion.newStates++;
@@ -1519,53 +2252,105 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1519
2252
  try {
1520
2253
  const violated = search.findViolatedInvariant(successor.state, state);
1521
2254
  if (violated) {
1522
- return reportViolation("invariant-violation", {
1523
- name: violated.name,
1524
- trace: getTrace(index, successor),
1525
- });
2255
+ return withOutDegrees(
2256
+ reportViolation("invariant-violation", {
2257
+ name: violated.name,
2258
+ ...getTrace(index, successor),
2259
+ }),
2260
+ );
1526
2261
  }
1527
2262
  } catch (error) {
1528
- // TLC prints the outdegree when it cannot reproduce the failure, as for an invariant here.
1529
- return toFailure(error, getTrace(index, successor), undefined, getPartialOutDegrees());
2263
+ if (isStackOverflow(error)) throw error;
2264
+ // TLC replays the expansion and skips the invariants of a state it has seen, the failed one
2265
+ // included unless the constraints exclude it. When the replay fails, TLC reports where and
2266
+ // leaves out the outdegree.
2267
+ const replay = getOutput(() => replayNext(index));
2268
+ return toFailure(
2269
+ error,
2270
+ appendTraceOutput(getFailedTrace(index, successor), replay.lines),
2271
+ replay.result ?? { outDegrees: getFailureOutDegrees() },
2272
+ );
1530
2273
  }
1531
2274
  }
1532
2275
  const violatedProperty = search.findViolatedActionProperty(state, successor.state);
1533
2276
  if (violatedProperty) {
1534
- return reportViolation("liveness-violation", {
1535
- name: violatedProperty.name,
1536
- trace: getTrace(index, successor),
1537
- });
2277
+ return withOutDegrees(
2278
+ reportViolation("liveness-violation", {
2279
+ name: violatedProperty.name,
2280
+ ...getTrace(index, successor),
2281
+ }),
2282
+ );
1538
2283
  }
1539
2284
  if (!isNew) return undefined;
1540
2285
  if (!isCanonicalizedFirst) canonicalizeState(successor.state);
1541
2286
  markSeen(hash, states.length);
1542
- if (liveness) liveSuccessors.push({ index: states.length, state: successor.state });
1543
2287
  addState(successor.state, fingerprintState, index, successor.action);
1544
2288
  runtime.queueSize++;
1545
2289
  return undefined;
1546
2290
  };
1547
2291
 
1548
2292
  const outcome: { result: CheckResult | undefined } = { result: undefined };
2293
+ if (liveness) {
2294
+ options.onProgress?.({ kind: "liveness-prepared", branches: liveness.branches });
2295
+ }
2296
+ // TLC checks the assumptions once it has built the liveness checker in ModelChecker's
2297
+ // constructor.
2298
+ const assumptionViolation = findViolatedAssumption();
2299
+ if (assumptionViolation) return createResult("assumption-violation", assumptionViolation);
2300
+ options.onProgress?.({ kind: "initial-states-started" });
1549
2301
  if (spec.init !== undefined) {
1550
2302
  try {
1551
2303
  forEachInitialState(
1552
2304
  spec.init,
1553
2305
  environment,
1554
2306
  (state) => {
2307
+ reportInitialStatesProgress(runtime.initialStates, options.onProgress);
1555
2308
  try {
1556
2309
  outcome.result = visitInitialState(state);
1557
2310
  } catch (error) {
1558
- outcome.result = toFailure(error, [], state);
2311
+ const replay = getOutput(replayInit);
2312
+ outcome.result = toFailure(
2313
+ error,
2314
+ { trace: [], traceOutput: replay.lines },
2315
+ { initialState: state, ...replay.result, isInitial: true },
2316
+ );
1559
2317
  }
1560
2318
  return outcome.result !== undefined;
1561
2319
  },
1562
2320
  spec.scope,
1563
2321
  );
1564
2322
  } catch (error) {
1565
- return replayInitialStates(toFailure(error, []));
2323
+ // TLC prints an illegal initial state with null for each variable it leaves undefined, and
2324
+ // stops before it prints the statistics.
2325
+ if (error instanceof TlaIllegalStateError) {
2326
+ const illegal = toFailure(
2327
+ error,
2328
+ { trace: [] },
2329
+ { initialState: error.state.map((value) => value ?? createModelValue("null")) },
2330
+ );
2331
+ return {
2332
+ ...illegal,
2333
+ failure: illegal.failure && { ...illegal.failure, isWithoutStatistics: true },
2334
+ };
2335
+ }
2336
+ // TLC prints the error before it replays the initial predicate with its call stack.
2337
+ const replay = getOutput(replayInit);
2338
+ return toFailure(
2339
+ error,
2340
+ { trace: [], traceOutput: replay.lines },
2341
+ { ...replay.result, isInitial: true },
2342
+ );
1566
2343
  }
1567
2344
  }
1568
- if (outcome.result) return replayInitialStates(outcome.result);
2345
+ if (outcome.result) return outcome.result;
2346
+ statistics.initialStates = {
2347
+ generated: runtime.initialStates,
2348
+ distinct: runtime.distinctStates,
2349
+ };
2350
+ options.onProgress?.({
2351
+ kind: "initial-states-computed",
2352
+ initialStates: statistics.initialStates,
2353
+ });
1569
2354
 
1570
2355
  const next = spec.next;
1571
2356
  if (next === undefined) {
@@ -1594,9 +2379,8 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1594
2379
  spec.scope,
1595
2380
  );
1596
2381
  }
1597
- nextActions.value ??= getNextActions(config, environment, specification.instanceActions);
1598
2382
  const progress = { isStopped: false };
1599
- return nextActions.value.reduce((count, action) => {
2383
+ return getSpecNextActions().reduce((count, action) => {
1600
2384
  if (progress.isStopped) return count;
1601
2385
  return (
1602
2386
  count +
@@ -1613,90 +2397,240 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1613
2397
  );
1614
2398
  }, 0);
1615
2399
  };
1616
- const expandState = (index: number) => {
2400
+ // TLC's worker adds a state to the behavior graph even after its next states fail or violate a
2401
+ // property, and prints the call stack of an error in that, unless the error is a
2402
+ // FingerprintException, which the worker doesn't catch. TLC 1.7.4 prints none.
2403
+ const getLiveCallStack = (index: number, liveSuccessors: LiveSuccessor[]) => {
2404
+ if (!liveness || is174) return undefined;
2405
+ const replay = getReplayFailure((tracing) =>
2406
+ liveness.addState(index, states[index], liveSuccessors, tracing),
2407
+ );
2408
+ return replay?.callStack.length && !replay.fingerprint ? replay.callStack : undefined;
2409
+ };
2410
+ // TLC's worker adds the state to the behavior graph after it prints the trace. On an error in that,
2411
+ // it adds the state again to print the call stack instead of replaying the next-state relation,
2412
+ // which TLC 1.7.4 doesn't.
2413
+ const addFailedLiveState = (index: number, liveSuccessors: LiveSuccessor[]) => {
2414
+ try {
2415
+ liveness?.addState(index, states[index], liveSuccessors);
2416
+ return undefined;
2417
+ } catch (error) {
2418
+ if (!(error instanceof TlaEvaluationError)) throw error;
2419
+ return getLiveCallStack(index, liveSuccessors);
2420
+ }
2421
+ };
2422
+ const replayFailedNext = (index: number, liveSuccessors: LiveSuccessor[]) => {
2423
+ const live = getOutput(() => addFailedLiveState(index, liveSuccessors));
2424
+ if (live.result) {
2425
+ const result = { callStack: live.result, fingerprint: undefined, isLiveCallStack: true };
2426
+ return { result, lines: live.lines };
2427
+ }
2428
+ const replay = getOutput(() => replayNext(index));
2429
+ return { result: replay.result, lines: [...live.lines, ...replay.lines] };
2430
+ };
2431
+ // TLC reports a stack overflow while it computes next states without replaying it, with the
2432
+ // behavior up to the state it expands.
2433
+ const reportNextStateOverflow = (index: number) =>
2434
+ toFailure(createStackOverflowError(), getStateTrace(index));
2435
+ // After the trace, TLC replays the next-state relation with its call stack, printing again.
2436
+ const reportNextStateFailure = (
2437
+ error: unknown,
2438
+ index: number,
2439
+ liveSuccessors: LiveSuccessor[],
2440
+ ) => {
2441
+ if (isStackOverflow(error)) return reportNextStateOverflow(index);
2442
+ const replay = replayFailedNext(index, liveSuccessors);
2443
+ return toFailure(
2444
+ withNextStateExitCode(error),
2445
+ appendTraceOutput(getStateTrace(index), replay.lines),
2446
+ { isNextState: true, ...replay.result },
2447
+ );
2448
+ };
2449
+ const expandState = (index: number, liveSuccessors: LiveSuccessor[]) => {
1617
2450
  const state = states[index];
1618
- const liveSuccessors: LiveSuccessor[] = [];
1619
2451
  const source = stateWriter && getGraphState(state, depths[index]);
1620
2452
  const successorCount = forEachActionSuccessor(state, (successor, action) => {
1621
2453
  try {
1622
2454
  outcome.result = visitSuccessor(index, successor, liveSuccessors, source, action);
1623
2455
  } catch (error) {
1624
- // TLC reports a successor it cannot fingerprint as a failure of the state it expands.
1625
- if (current.isFingerprinting) throw error;
1626
- const failure = toFailure(error, getTrace(index, successor));
1627
- outcome.result = isStackOverflow(error) ? failure : replaySuccessors(failure, index);
2456
+ if (isStackOverflow(error)) {
2457
+ outcome.result = reportNextStateOverflow(index);
2458
+ return true;
2459
+ }
2460
+ // TLC 1.7.4 reports the wrapped error without the trace, except for a failed property,
2461
+ // which it reports with the trace before it rethrows. The error stops its worker before it
2462
+ // adds the state to the behavior graph.
2463
+ const replay = is174
2464
+ ? getOutput(() => replayNext(index))
2465
+ : replayFailedNext(index, liveSuccessors);
2466
+ if (is174 && error instanceof TlaEvaluationError && !headedErrors.has(error)) {
2467
+ outcome.result = toFailure(
2468
+ new TlaEvaluationError(`${getWrappedException(error)}${error.message}`, error),
2469
+ appendTraceOutput({ trace: [] }, replay.lines),
2470
+ { isNextState: true, ...replay.result },
2471
+ );
2472
+ return true;
2473
+ }
2474
+ // A successor TLC can't fingerprint fails again as TLC prints it in the trace, which TLC
2475
+ // reports as an exception it didn't expect.
2476
+ const isTraceFailed = getFingerprintState(successor.state).some(
2477
+ (value) => getFingerprintError(value) !== undefined,
2478
+ );
2479
+ const traceFailure =
2480
+ isTraceFailed && error instanceof TlaEvaluationError
2481
+ ? getFailureMessage(
2482
+ isEvalException(error)
2483
+ ? new TlaEvaluationError(`${UNEXPECTED_EVAL_EXCEPTION}${error.message}`)
2484
+ : error,
2485
+ true,
2486
+ )
2487
+ : undefined;
2488
+ outcome.result = toFailure(
2489
+ error,
2490
+ appendTraceOutput(
2491
+ traceFailure ? getStateTrace(index) : getFailedTrace(index, successor),
2492
+ replay.lines,
2493
+ ),
2494
+ { isNextState: true, ...replay.result, traceFailure },
2495
+ );
1628
2496
  }
1629
2497
  return outcome.result !== undefined;
1630
2498
  });
1631
2499
  current.isExpanding = false;
1632
- if (outcome.result) return outcome.result;
1633
- if (successorCount === 0 && config.checkDeadlock) {
1634
- return reportViolation("deadlock", { name: "deadlock", trace: getStateTrace(index) });
2500
+ const result = outcome.result;
2501
+ // TLC 1.7.4's worker stops at a violation.
2502
+ if (result?.violation && !is174) {
2503
+ const live = getOutput(() => addFailedLiveState(index, liveSuccessors));
2504
+ return {
2505
+ ...result,
2506
+ violation: appendTraceOutput(result.violation, live.lines),
2507
+ ...(live.result && { liveCallStack: live.result }),
2508
+ };
1635
2509
  }
1636
- try {
2510
+ if (result) return result;
2511
+ const addLiveState = () => {
2512
+ if (liveness && source && is174) stateWriter?.writeStuttering(source);
1637
2513
  const accepted = liveness?.addState(index, state, liveSuccessors);
1638
2514
  if (!liveness || !accepted) return undefined;
1639
2515
  const steps = getPathSteps(accepted);
1640
- const properties = liveness.getViolatedProperties(
2516
+ const properties = getViolatedProperties(
2517
+ liveness,
1641
2518
  steps.map((step) => step.state),
1642
2519
  steps.length - 1,
1643
2520
  );
1644
2521
  return reportViolation("property-violation", {
1645
2522
  name: properties[0],
1646
2523
  properties,
1647
- trace: toTrace(steps, accepted),
2524
+ ...toTrace(steps, accepted, { known: 0 }),
1648
2525
  });
2526
+ };
2527
+ if (successorCount === 0 && config.checkDeadlock) {
2528
+ const deadlock = reportViolation("deadlock", { name: "deadlock", ...getStateTrace(index) });
2529
+ // TLC's worker still adds the deadlocked state to the behavior graph after it reports the
2530
+ // deadlock, and reports a temporal property that this violates. Then it counts the state as
2531
+ // expanded.
2532
+ const live = getOutput(() => {
2533
+ try {
2534
+ return { additional: addLiveState()?.violation };
2535
+ } catch (error) {
2536
+ if (!(error instanceof TlaEvaluationError)) throw error;
2537
+ return { isFailed: true, callStack: getLiveCallStack(index, liveSuccessors) };
2538
+ }
2539
+ });
2540
+ const reported = deadlock.violation
2541
+ ? { ...deadlock, violation: appendTraceOutput(deadlock.violation, live.lines) }
2542
+ : deadlock;
2543
+ // An error in adding the state stops TLC 1.7.4's worker before it counts the state.
2544
+ const counted = withOutDegrees(
2545
+ reported,
2546
+ live.result.isFailed ? getFailureOutDegrees() : getPartialOutDegrees(),
2547
+ );
2548
+ if (live.result.additional)
2549
+ return { ...counted, additionalViolation: live.result.additional };
2550
+ return live.result.callStack ? { ...counted, liveCallStack: live.result.callStack } : counted;
2551
+ }
2552
+ try {
2553
+ return addLiveState();
1649
2554
  } catch (error) {
1650
- return toFailure(error, getStateTrace(index), undefined, getPartialOutDegrees());
2555
+ // TLC 1.7.4's worker reports an error in adding a state to the behavior graph as an exception
2556
+ // it didn't expect, without the trace or a call stack, and exits as for any general error.
2557
+ if (is174 && error instanceof TlaEvaluationError) {
2558
+ const unexpected = new TlaEvaluationError(
2559
+ `${isEvalException(error) ? UNEXPECTED_EVAL_EXCEPTION : UNEXPECTED_EXCEPTION}${error.message}`,
2560
+ );
2561
+ return toFailure(
2562
+ setExitCode(unexpected, EXIT_STATUS.error),
2563
+ { trace: [] },
2564
+ { outDegrees: getFailureOutDegrees() },
2565
+ );
2566
+ }
2567
+ // TLC's Worker#doNextCheckLiveness adds the state again to find the call stack, prints it
2568
+ // before the error, and reports the error as one in computing next states.
2569
+ const replay = getReplayFailure((tracing) =>
2570
+ liveness?.addState(index, state, liveSuccessors, tracing),
2571
+ );
2572
+ return toFailure(error, getStateTrace(index), {
2573
+ outDegrees: getFailureOutDegrees(),
2574
+ callStack: replay?.callStack.length ? replay.callStack : undefined,
2575
+ isNextState: true,
2576
+ isCallStackFirst: true,
2577
+ });
1651
2578
  }
1652
2579
  };
1653
- // TLC names the action when the next-state relation has more than one, and prints the
1654
- // incomplete successor with null for each variable it leaves undefined.
1655
- const reportIncompleteSuccessor = (error: TlaIncompleteStateError, index: number) => {
1656
- nextActions.value ??= getNextActions(config, environment, specification.instanceActions);
1657
- const actions = nextActions.value;
1658
- const action =
1659
- actions.length === 1 ? actions[0] : actions.find((item) => item.name === error.action);
1660
- const variables = `variable${error.missing.length > 1 ? "s are" : " is"} not defined: ${error.missing.join(", ")}.\n`;
1661
- runtime.generatedStates++;
1662
- return toFailure(
1663
- actions.length === 1
1664
- ? error
1665
- : new TlaEvaluationError(
1666
- `Successor state is not completely specified by action ${error.action} of the next-state relation. The following ${variables}`,
1667
- ),
1668
- [
1669
- ...getStateTrace(index),
1670
- {
1671
- action: error.action,
1672
- label: action && getActionLabel(action),
1673
- state: toRecord(error.state.map((value) => value ?? createModelValue("null"))),
1674
- },
1675
- ],
1676
- );
2580
+ // TLC's Liveness#printStutteringCounterExampleWarning.
2581
+ const getStutteringWarning = () => {
2582
+ const name = config.specification;
2583
+ const book =
2584
+ "(compare Chapter 8, page 87ff of Specifying Systems at https://lamport.azurewebsites.net/tla/book.html).";
2585
+ if (name === undefined) {
2586
+ return {
2587
+ code: MESSAGE_CODE.noSpecificationButProperty,
2588
+ text: `The stuttering counterexample above may be caused by the absence of a behavior specification (SPECIFICATION). Only INIT and NEXT have been provided, so TLC permits infinite stuttering. To rule out such counterexamples, use SPECIFICATION Spec, with Spec asserting a suitable fairness constraint ${book}`,
2589
+ };
2590
+ }
2591
+ const range = getDefinition(name, environment)?.location.range;
2592
+ if (spec.temporals.length > 0 || !range) return undefined;
2593
+ return {
2594
+ code: MESSAGE_CODE.noFairnessButProperty,
2595
+ text: `The stuttering counterexample above may be caused by the absence of a fairness constraint in the behavior specification ${name} defined at ${formatRange(range)}. To rule out such counterexamples, conjoin a suitable fairness constraint to ${name} ${book}`,
2596
+ };
1677
2597
  };
1678
2598
  // TLC names the properties and the step back into the cycle from the states it prints.
1679
2599
  const reportLasso = (checker: LivenessChecker, lasso: Lasso) => {
1680
2600
  const path = [...lasso.prefix, ...lasso.cycle];
1681
2601
  const loopStart = lasso.prefix.length;
1682
2602
  const steps = getPathSteps(path, loopStart);
1683
- const trace = toTrace(steps, path, loopStart);
1684
- const properties = checker.getViolatedProperties(
2603
+ const trace = toTrace(steps, path, { loopStart, known: 0 }).trace;
2604
+ const properties = getViolatedProperties(
2605
+ checker,
1685
2606
  steps.map((step) => step.state),
1686
2607
  loopStart,
1687
2608
  );
1688
2609
  const back = path[loopStart];
1689
2610
  const last = path[path.length - 1];
1690
2611
  const lastState = steps[steps.length - 1].state;
1691
- const loopLabel =
1692
- back === last ? undefined : withoutOutput(() => getLabel(last, lastState, states[back]));
2612
+ const loop =
2613
+ back === last
2614
+ ? { result: undefined, lines: [] }
2615
+ : getOutput(() => findStepAction(last, lastState, states[back], false));
2616
+ const isStutteringWarned = back === last && lasso.isCycleConstrained;
1693
2617
  return reportViolation(
1694
2618
  "liveness-violation",
1695
- { name: properties[0], properties, trace, loopStart, loopLabel },
2619
+ {
2620
+ name: properties[0],
2621
+ properties,
2622
+ trace,
2623
+ traceOutput: loop.lines,
2624
+ loopStart,
2625
+ loopLabel: loop.result && getActionLabel(loop.result, options.version),
2626
+ warning: isStutteringWarned ? getStutteringWarning() : undefined,
2627
+ },
1696
2628
  () =>
1697
2629
  back === last
1698
- ? trace[trace.length - 1].action
1699
- : findSuccessorWithFingerprint(lastState, back)?.action,
2630
+ ? getStepAction(trace[trace.length - 1])
2631
+ : loop.result
2632
+ ? toActionValue(loop.result)
2633
+ : createActionRecord(findSuccessorWithFingerprint(lastState, back)?.action),
1700
2634
  );
1701
2635
  };
1702
2636
  const isPeriodic = liveness !== undefined && options.livenessCheck !== "final";
@@ -1704,11 +2638,19 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1704
2638
  const periodic = { at: startedAt + PERIODIC_START, size: 1, time: 0 };
1705
2639
  const findPeriodicViolation = (expanded: number) => {
1706
2640
  const now = performance.now();
1707
- periodic.at = now + PROGRESS_INTERVAL;
1708
2641
  const isGrown = (expanded - periodic.size) / periodic.size > LIVENESS_GROWTH;
1709
2642
  if (!isGrown || periodic.time > (now - startedAt) * LIVENESS_RATIO) return undefined;
1710
2643
  periodic.size = expanded;
1711
- const lasso = liveness?.findViolation();
2644
+ if (!liveness) return undefined;
2645
+ options.onProgress?.({
2646
+ kind: "liveness-started",
2647
+ branches: liveness.branches,
2648
+ isComplete: false,
2649
+ states: expanded,
2650
+ statistics: createResult("success"),
2651
+ });
2652
+ const lasso = liveness.findViolation();
2653
+ if (!lasso) options.onProgress?.({ kind: "liveness-finished" });
1712
2654
  periodic.time += performance.now() - now;
1713
2655
  return lasso;
1714
2656
  };
@@ -1717,35 +2659,57 @@ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefine
1717
2659
  current.candidate = undefined;
1718
2660
  runtime.queueSize = states.length - index - 1;
1719
2661
  current.isExpanding = true;
2662
+ const liveSuccessors: LiveSuccessor[] = [];
1720
2663
  try {
1721
- outcome.result = expandState(index);
2664
+ outcome.result = expandState(index, liveSuccessors);
1722
2665
  } catch (error) {
1723
- const failure =
1724
- error instanceof TlaIncompleteStateError
1725
- ? reportIncompleteSuccessor(error, index)
1726
- : toFailure(toNextStateError(error), getStateTrace(index));
1727
2666
  outcome.result =
1728
- error instanceof TlaIncompleteStateError || isStackOverflow(error)
1729
- ? failure
1730
- : replaySuccessors(failure, index);
2667
+ error instanceof TlaIncompleteSuccessorError
2668
+ ? reportIncompleteSuccessor(index, error)
2669
+ : reportNextStateFailure(error, index, liveSuccessors);
1731
2670
  }
1732
2671
  if (outcome.result) return outcome.result;
1733
2672
  outDegrees[getOutDegreeBucket()]++;
1734
2673
  expansion.newStates = 0;
1735
- if (isPeriodic && performance.now() >= periodic.at) {
1736
- const lasso = findPeriodicViolation(index + 1);
2674
+ // TLC's AbstractChecker#runTLC checks the liveness properties on the state graph so far, then
2675
+ // reports how far the search got.
2676
+ if ((isPeriodic || options.onProgress) && performance.now() >= periodic.at) {
2677
+ periodic.at = performance.now() + PROGRESS_INTERVAL;
2678
+ const lasso = isPeriodic ? findPeriodicViolation(index + 1) : undefined;
1737
2679
  if (liveness && lasso) return reportLasso(liveness, lasso);
2680
+ options.onProgress?.({ kind: "progress", statistics: createResult("success") });
1738
2681
  }
1739
2682
  }
1740
2683
 
1741
2684
  current.index = -1;
1742
2685
  current.candidate = undefined;
2686
+ if (liveness) {
2687
+ options.onProgress?.({
2688
+ kind: "liveness-started",
2689
+ branches: liveness.branches,
2690
+ isComplete: true,
2691
+ states: runtime.distinctStates,
2692
+ statistics: createResult("success"),
2693
+ });
2694
+ }
1743
2695
  const lasso = liveness?.findViolation();
1744
2696
  if (liveness && lasso) return reportLasso(liveness, lasso);
1745
2697
 
1746
- const postconditionViolation = search.findPostconditionViolation();
1747
- if (postconditionViolation) {
1748
- return createResult("postcondition-violation", { ...postconditionViolation, trace: [] });
2698
+ // TLC finishes the check of the temporal properties before it checks the postconditions.
2699
+ if (liveness) options.onProgress?.({ kind: "liveness-finished" });
2700
+ try {
2701
+ const postcondition = search.findPostconditionViolation();
2702
+ if (postcondition) {
2703
+ return createResult("postcondition-violation", {
2704
+ name: postcondition.name,
2705
+ message: postcondition.message,
2706
+ counts: postcondition.counts,
2707
+ trace: [],
2708
+ postcondition,
2709
+ });
2710
+ }
2711
+ } catch (error) {
2712
+ return toFailure(error, { trace: [] });
1749
2713
  }
1750
2714
  return createSuccess();
1751
2715
  };