tla-ts 0.0.3-dev.79f7ed7 → 0.0.3-dev.852fbc8

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 (50) hide show
  1. package/README.md +16 -2
  2. package/dist/index.cjs +1 -1
  3. package/dist/index.d.cts +55 -22
  4. package/dist/index.d.ts +55 -22
  5. package/dist/index.js +1 -1
  6. package/dist/parallel-worker.cjs +1 -1
  7. package/dist/parallel-worker.js +2 -2
  8. package/dist/parallel.cjs +1 -1
  9. package/dist/parallel.js +2 -2
  10. package/dist/run-cli.cjs +19 -16
  11. package/dist/run-cli.js +20 -17
  12. package/dist/transfer.cjs +37 -16
  13. package/dist/transfer.js +37 -16
  14. package/package.json +1 -1
  15. package/src/ast.ts +93 -0
  16. package/src/check.ts +511 -99
  17. package/src/cli-options.ts +11 -5
  18. package/src/codegen.ts +15 -22
  19. package/src/config.ts +224 -170
  20. package/src/dependencies.ts +2 -2
  21. package/src/environment.ts +116 -28
  22. package/src/errors.ts +87 -3
  23. package/src/evaluate.ts +252 -156
  24. package/src/exit-codes.ts +39 -42
  25. package/src/instances.ts +16 -15
  26. package/src/levels.ts +62 -34
  27. package/src/lexer.ts +5 -1
  28. package/src/live-check.ts +772 -0
  29. package/src/liveness.ts +120 -543
  30. package/src/parallel-worker.ts +7 -3
  31. package/src/parallel.ts +20 -4
  32. package/src/parser.ts +33 -11
  33. package/src/resolve.ts +122 -44
  34. package/src/run-cli.ts +112 -20
  35. package/src/runtime.ts +3 -1
  36. package/src/spec-description.ts +19 -8
  37. package/src/standard-modules.ts +10 -9
  38. package/src/state-graph.ts +157 -0
  39. package/src/subexpressions.ts +10 -10
  40. package/src/successors.ts +183 -39
  41. package/src/symmetry.ts +30 -8
  42. package/src/tableau.ts +51 -24
  43. package/src/tlc-ext.ts +29 -12
  44. package/src/tlc-module.ts +14 -33
  45. package/src/tlc-modules.ts +4 -0
  46. package/src/tlc-order.ts +25 -7
  47. package/src/tlc-random.ts +9 -6
  48. package/src/tlc-summary.ts +20 -5
  49. package/src/value-sources.ts +29 -0
  50. package/src/values.ts +179 -57
package/src/check.ts CHANGED
@@ -1,32 +1,46 @@
1
- import type { Assumption, Definition, Expression, SourceLocation } from "./ast";
1
+ import {
2
+ getChildren,
3
+ isLocallyResolved,
4
+ type Assumption,
5
+ type Definition,
6
+ type Expression,
7
+ type SourceLocation,
8
+ } from "./ast";
2
9
  import { parseConfig, type ConfigValue, type ModelConfig } from "./config";
3
10
  import { getReadVariables } from "./dependencies";
4
11
  import { createEnvironment } from "./environment";
5
- import { getErrorExitCode, TlaConfigError, TlaEvaluationError, TlaModuleError } from "./errors";
6
- import { EXIT_STATUS, setExitCode, setNextStatePhase, withLivenessExitCode } from "./exit-codes";
12
+ import {
13
+ getErrorExitCode,
14
+ isStackOverflow,
15
+ formatRange,
16
+ STACK_OVERFLOW,
17
+ TlaConfigError,
18
+ TlaEvaluationError,
19
+ TlaIllegalStateError,
20
+ TlaIncompleteStateError,
21
+ TlaModuleError,
22
+ UNEXPECTED_EXCEPTION,
23
+ } from "./errors";
24
+ import { EXIT_STATUS, setExitCode, withLivenessExitCode } from "./exit-codes";
7
25
  import {
8
26
  describeRange,
9
27
  evaluate,
10
28
  expectBoolean,
11
- formatRange,
12
- getChildren,
13
29
  getDefinition,
14
30
  isConstantLevel,
15
31
  isImpure,
16
- isLocallyResolved,
17
32
  type Context,
18
33
  type Environment,
19
34
  type Scope,
20
35
  } from "./evaluate";
21
36
  import {
22
37
  createLivenessChecker,
23
- expandTemporal,
24
- getLevel,
25
38
  type Lasso,
39
+ type LiveGraph,
40
+ type LivenessChecker,
26
41
  type LiveSuccessor,
27
- type ScopedExpression,
28
- type TemporalProperty,
29
- } from "./liveness";
42
+ } from "./live-check";
43
+ import { expandTemporal, getLevel, type ScopedExpression, type TemporalProperty } from "./liveness";
30
44
  import { ACTION_LEVEL, createLevelAnalyzer, TEMPORAL_LEVEL } from "./levels";
31
45
  import { prettyPrint } from "./pretty-print";
32
46
  import {
@@ -38,19 +52,29 @@ import {
38
52
  } from "./successors";
39
53
  import {
40
54
  getActionLabel,
55
+ getActionSignature,
41
56
  getNextActions,
42
57
  getSpecificationValue,
43
58
  type SpecAction,
44
59
  } from "./spec-description";
60
+ import {
61
+ createStateWriter,
62
+ type GraphState,
63
+ type StateDump,
64
+ type StateWriter,
65
+ } from "./state-graph";
45
66
  import { getRepresentative, getSymmetryGroup } from "./symmetry";
46
- import { getTlcStringOrder, getTlcVariableOrder } from "./tlc-order";
67
+ import { getTlcStringOrder, getTlcDeclarationOrder } from "./tlc-order";
47
68
  import { createTlcFingerprinter, getTlcFingerprint } from "./tlc-random";
48
69
  import { createCanonicalizer } from "./canonical";
49
70
  import { getPossibleCounts, type CheckerRuntime } from "./runtime";
50
71
  import { createCounterExample } from "./tlc-ext";
72
+ import { getFingerprintTrace, valueSources } from "./value-sources";
51
73
  import { getFingerprintDistance, OUT_DEGREE_BUCKETS } from "./tlc-summary";
52
74
  import {
53
75
  combineHash,
76
+ createModelValue,
77
+ formatState,
54
78
  formatValue,
55
79
  getValueHash,
56
80
  isFunctionValue,
@@ -74,6 +98,8 @@ export interface CheckOptions {
74
98
  workers?: number;
75
99
  // TLC's -lncheck: "final" checks liveness only on the complete state graph.
76
100
  livenessCheck?: "default" | "final";
101
+ // TLC's -dump: writes the reachable states, or with `dot` the state graph, through writeFile.
102
+ dump?: StateDump;
77
103
  }
78
104
 
79
105
  export type CheckStatus =
@@ -95,6 +121,8 @@ export interface TraceStep {
95
121
 
96
122
  export interface Violation {
97
123
  name: string;
124
+ // Every temporal property that a liveness counterexample violates, in the configuration's order.
125
+ properties?: string[];
98
126
  trace: TraceStep[];
99
127
  loopStart: number | undefined;
100
128
  loopLabel?: string;
@@ -115,6 +143,25 @@ export interface EvaluationFailure {
115
143
  trace: TraceStep[];
116
144
  initialState: Record<string, Value> | undefined;
117
145
  exitCode: number;
146
+ replay?: Replay;
147
+ isWithoutStatistics?: boolean;
148
+ }
149
+
150
+ // TLC replays a failed step to print the expressions it was evaluating when the replay failed.
151
+ export interface Replay {
152
+ output: string[];
153
+ callStack: string[] | undefined;
154
+ fingerprint?: Fingerprint;
155
+ // The worker that fails to check liveness replays the step at once, so TLC prints the stack
156
+ // before the error, and only when it holds a frame.
157
+ isBeforeError?: boolean;
158
+ }
159
+
160
+ // TLC reports an error from a method of a value that has a source as one it was unable to
161
+ // fingerprint. With an empty stack, it lists the sources of the values instead.
162
+ export interface Fingerprint {
163
+ sources: string[];
164
+ reason: string;
118
165
  }
119
166
 
120
167
  export interface CheckResult {
@@ -226,7 +273,7 @@ const getConstantValue = (name: string, definition: Definition, environment: Env
226
273
  try {
227
274
  return evaluate(createIdentifier(name), getContext(environment, undefined, undefined));
228
275
  } catch (error) {
229
- if (error instanceof TlaEvaluationError) return undefined;
276
+ if (error instanceof TlaEvaluationError || isStackOverflow(error)) return undefined;
230
277
  throw error;
231
278
  }
232
279
  };
@@ -255,8 +302,11 @@ const getInvariants = (names: string[], environment: Environment) => {
255
302
  levels.params.size === 0
256
303
  ? ""
257
304
  : "\nNote that a bug can cause TLC to incorrectly report this error.\nIf you believe your TLA+ or PlusCal specification to be correct,\nplease check if this bug described in LevelNode.java starting at line 590ff affects you.";
258
- throw new TlaConfigError(
259
- `The invariant ${name} is not a state predicate (one with no primes or temporal operators).${note}`,
305
+ throw setExitCode(
306
+ new TlaConfigError(
307
+ `The invariant ${name} is not a state predicate (one with no primes or temporal operators).${note}`,
308
+ ),
309
+ EXIT_STATUS.safetyEvaluationFailure,
260
310
  );
261
311
  }
262
312
  return [{ name, expression: createIdentifier(name), scope: undefined }];
@@ -354,8 +404,11 @@ const getSpecification = (config: ModelConfig, environment: Environment): Specif
354
404
  conjunct.kind === "Always" &&
355
405
  getLevel(conjunct.expression, item.scope, environment) < ACTION_LEVEL
356
406
  ) {
357
- throw new TlaConfigError(
358
- `TLC cannot handle []P in the specification ${config.specification} when P is a state predicate`,
407
+ throw setExitCode(
408
+ new TlaConfigError(
409
+ `TLC cannot handle the temporal formula ${describeRange(conjunct.expression)}`,
410
+ ),
411
+ EXIT_STATUS.error,
359
412
  );
360
413
  }
361
414
  const level = getLevel(conjunct, item.scope, environment);
@@ -425,12 +478,12 @@ const getProperties = (config: ModelConfig, environment: Environment): Propertie
425
478
  config.properties.forEach((name) => {
426
479
  const definition = getConfigPredicate("property", name, environment);
427
480
  if (!definition) return;
428
- expandTemporal(definition.body, undefined, environment, true).forEach((item) => {
481
+ expandTemporal(definition.body, undefined, environment, true, name).forEach((item) => {
429
482
  const conjunct = item.expression;
430
483
  if (isConstantTrue(item, environment, "property")) return;
431
484
  if (conjunct.kind === "Always" && conjunct.expression.kind === "BoxAction") {
432
485
  properties.actionProperties.push({
433
- name,
486
+ name: item.name,
434
487
  box: conjunct.expression,
435
488
  action: conjunct.expression.action,
436
489
  subscript: conjunct.expression.subscript,
@@ -442,12 +495,22 @@ const getProperties = (config: ModelConfig, environment: Environment): Propertie
442
495
  conjunct.kind === "Always" &&
443
496
  getLevel(conjunct.expression, item.scope, environment) <= 1
444
497
  ) {
445
- properties.invariants.push({ name, expression: conjunct.expression, scope: item.scope });
498
+ // TLC names the invariant []P after P when P is an operator name.
499
+ const expression = conjunct.expression;
500
+ properties.invariants.push({
501
+ name: expression.kind === "Identifier" ? expression.name : item.name,
502
+ expression,
503
+ scope: item.scope,
504
+ });
446
505
  return;
447
506
  }
448
507
  const level = getLevel(conjunct, item.scope, environment);
449
508
  if (level < ACTION_LEVEL) {
450
- properties.initialPredicates.push({ name, expression: conjunct, scope: item.scope });
509
+ properties.initialPredicates.push({
510
+ name: item.name,
511
+ expression: conjunct,
512
+ scope: item.scope,
513
+ });
451
514
  return;
452
515
  }
453
516
  if (level === ACTION_LEVEL) {
@@ -507,7 +570,9 @@ const getMembership = (
507
570
  const getStateChecks = (named: NamedExpression[], environment: Environment): StateCheck[] =>
508
571
  named.flatMap((item) =>
509
572
  getConjuncts(item.expression, environment).map((expression) => {
510
- const variables = getReadVariables(expression, environment);
573
+ // A LET or an argument in the scope can read variables the expression doesn't name.
574
+ const variables =
575
+ item.scope === undefined ? getReadVariables(expression, environment) : undefined;
511
576
  return {
512
577
  name: item.name,
513
578
  expression,
@@ -754,11 +819,13 @@ export const createSearch = (
754
819
  if (view !== undefined || isFingerprintedLikeTlc) {
755
820
  return BigInt64Array.from(states, getTlcStateFingerprint);
756
821
  }
757
- const indices = getTlcOrder();
758
- const getFingerprint = createTlcFingerprinter();
759
- return BigInt64Array.from(fingerprintStates, (state) =>
760
- getFingerprint(indices.map((index) => state[index])),
822
+ const fingerprints = new BigInt64Array(fingerprintStates.length);
823
+ const fingerprint = createTlcFingerprinter(
824
+ getTlcOrder(),
825
+ new Int32Array(fingerprints.buffer),
761
826
  );
827
+ fingerprintStates.forEach(fingerprint);
828
+ return fingerprints;
762
829
  },
763
830
  getFingerprintState: (state) => {
764
831
  if (isFingerprintedLikeTlc) return [String(getTlcStateFingerprint(state))];
@@ -790,11 +857,17 @@ export const createSearch = (
790
857
  }
791
858
  }),
792
859
  satisfiesConstraints: (state, parent) =>
793
- constraints.every(
794
- (constraint) =>
795
- isUnchangedFor(constraint, state, parent) ||
796
- holdsLikeTlc(constraint.expression, getContext(environment, state, undefined)),
797
- ),
860
+ constraints.every((constraint) => {
861
+ try {
862
+ return (
863
+ isUnchangedFor(constraint, state, parent) ||
864
+ holdsLikeTlc(constraint.expression, getContext(environment, state, undefined))
865
+ );
866
+ } catch (error) {
867
+ // TLC reports a failing constraint on a successor like a failure of the next-state relation.
868
+ throw parent ? toNextStateError(error) : error;
869
+ }
870
+ }),
798
871
  findFailedInitialPredicate: (state) =>
799
872
  properties.initialPredicates.find(
800
873
  (predicate) =>
@@ -820,18 +893,20 @@ export const createSearch = (
820
893
  )
821
894
  );
822
895
  } catch (error) {
823
- throw withHeadline(error, `Evaluating action property ${property.name} failed.`);
896
+ throw withHeadline(
897
+ withNextStateExitCode(error),
898
+ `Evaluating action property ${property.name} failed.`,
899
+ );
824
900
  }
825
901
  }),
826
902
  satisfiesActionConstraints: (state, next) =>
827
- actionConstraints.every((constraint) =>
828
- holdsLikeTlc(
829
- constraint.expression,
830
- getContext(environment, state, next),
831
- (expression) =>
832
- `TLC threw an unexpected exception.\nThis was probably caused by an error in the spec or model.\nSee the User Output or TLC Console for clues to what happened.\nThe exception was a java.lang.RuntimeException\n: ${getExpectedBoolean(expression, environment)}`,
833
- ),
834
- ),
903
+ actionConstraints.every((constraint) => {
904
+ try {
905
+ return holdsLikeTlc(constraint.expression, getContext(environment, state, next));
906
+ } catch (error) {
907
+ throw toNextStateError(error);
908
+ }
909
+ }),
835
910
  trackStatePossible:
836
911
  statePossible.length === 0
837
912
  ? ignorePossible
@@ -857,6 +932,64 @@ export const createSearch = (
857
932
  };
858
933
  };
859
934
 
935
+ // TLC exits with the code of a standard module's failure only when the failure escapes the
936
+ // computation of next states. In every other phase, the phase decides the code.
937
+ const withNextStateExitCode = (error: unknown) =>
938
+ error instanceof TlaModuleError ? setExitCode(error, error.exitCode) : error;
939
+
940
+ // TLC reports a failure of the next-state relation, or of the liveness check of a step, as an
941
+ // unexpected exception, unless a standard module raised it as an EvalException.
942
+ const toNextStateError = (error: unknown) =>
943
+ error instanceof TlaEvaluationError &&
944
+ !(error instanceof TlaModuleError) &&
945
+ !(error instanceof TlaIncompleteStateError)
946
+ ? setExitCode(
947
+ new TlaEvaluationError(`${UNEXPECTED_EXCEPTION}${error.message}`, error),
948
+ getErrorExitCode(error),
949
+ )
950
+ : withNextStateExitCode(error);
951
+
952
+ const isRepeated = (frame: string, index: number, frames: string[]) =>
953
+ index > 0 && frames[index - 1] === frame;
954
+
955
+ // FingerprintException#getTrace numbers the sources from the outermost value and lists the innermost
956
+ // first.
957
+ const getSourceTrace = (sources: Expression[]) =>
958
+ sources
959
+ .flatMap((source) => (source.location.range ? [formatRange(source.location.range)] : []))
960
+ .filter((source, index, all) => !isRepeated(source, index, all))
961
+ .map((source, index) => `${index}) ${source}`)
962
+ .reverse();
963
+
964
+ // TLC keeps the stack only when an evaluation fails, and prints each expression on it once, however
965
+ // many times in a row it pushed it.
966
+ const getReplayedCallStack = (
967
+ replay: () => void,
968
+ trace: Expression[],
969
+ ): Pick<Replay, "callStack" | "fingerprint"> => {
970
+ try {
971
+ replay();
972
+ return { callStack: undefined };
973
+ } catch (error) {
974
+ if (!(error instanceof TlaEvaluationError)) return { callStack: [] };
975
+ const callStack = trace
976
+ .flatMap((expression) => {
977
+ const range = expression.location.range;
978
+ return range
979
+ ? [
980
+ `Line ${range.start.line}, column ${range.start.column} to line ${range.end.line}, column ${range.end.column} in ${range.module}`,
981
+ ]
982
+ : [];
983
+ })
984
+ .filter((frame, index, frames) => !isRepeated(frame, index, frames));
985
+ const sources = getFingerprintTrace(error);
986
+ return {
987
+ callStack,
988
+ fingerprint: sources && { sources: getSourceTrace(sources), reason: error.message },
989
+ };
990
+ }
991
+ };
992
+
860
993
  const withHeadline = (error: unknown, headline: string) =>
861
994
  error instanceof TlaEvaluationError
862
995
  ? setExitCode(
@@ -865,15 +998,30 @@ const withHeadline = (error: unknown, headline: string) =>
865
998
  )
866
999
  : error;
867
1000
 
1001
+ // TLC finishes the -dump file whether or not the search finds a violation.
868
1002
  export const checkSequentially = (options: CheckOptions): CheckResult => {
869
- setNextStatePhase(false);
1003
+ const stateWriter = options.dump && createStateWriter(options.dump, options.writeFile);
1004
+ try {
1005
+ return searchStates(options, stateWriter);
1006
+ } catch (error) {
1007
+ // TLC reports a stack overflow outside the search as a failure of its own, with exit code 255.
1008
+ throw isStackOverflow(error)
1009
+ ? setExitCode(new TlaEvaluationError(STACK_OVERFLOW), EXIT_STATUS.error)
1010
+ : error;
1011
+ } finally {
1012
+ stateWriter?.close();
1013
+ }
1014
+ };
1015
+
1016
+ const searchStates = (options: CheckOptions, stateWriter: StateWriter | undefined): CheckResult => {
870
1017
  const config = typeof options.config === "string" ? parseConfig(options.config) : options.config;
871
1018
  const onPrint = options.onPrint ?? console.log;
872
1019
  // TLC prints again while it rebuilds a trace, between the states it prints. Printing those lines
873
1020
  // before the trace would misplace them, so rebuilding a trace prints nothing.
874
- const output = { isMuted: false };
1021
+ const output = { isMuted: false, replayed: undefined as string[] | undefined };
875
1022
  const print = (text: string) => {
876
- if (!output.isMuted) onPrint(text);
1023
+ if (output.replayed) output.replayed.push(text);
1024
+ else if (!output.isMuted) onPrint(text);
877
1025
  };
878
1026
  const withoutOutput = <Result>(rebuild: () => Result) => {
879
1027
  output.isMuted = true;
@@ -935,9 +1083,9 @@ export const checkSequentially = (options: CheckOptions): CheckResult => {
935
1083
  ),
936
1084
  });
937
1085
 
938
- const search = createSearch(config, environment, () =>
939
- getTlcVariableOrder(options.source, options.loadModule),
940
- );
1086
+ const getVariableOrder = () =>
1087
+ getTlcDeclarationOrder(options.source, options.loadModule, "variable");
1088
+ const search = createSearch(config, environment, getVariableOrder);
941
1089
  const assumptionViolation = findAssumptionViolation(specification.assumptions, environment);
942
1090
  if (assumptionViolation) return createResult("assumption-violation", assumptionViolation);
943
1091
  if (!search) return createSuccess();
@@ -961,9 +1109,113 @@ export const checkSequentially = (options: CheckOptions): CheckResult => {
961
1109
  const spec = search.spec;
962
1110
  const getFingerprintState = search.getFingerprintState;
963
1111
  const nextActions = { value: undefined as SpecAction[] | undefined };
1112
+ const replayFailure = (
1113
+ result: CheckResult,
1114
+ replay: (tracedSearch: Search, traced: Environment) => void,
1115
+ isBeforeError = false,
1116
+ ): CheckResult => {
1117
+ if (!result.failure) return result;
1118
+ const trace: Expression[] = [];
1119
+ const traced: Environment = { ...environment, evaluators: new WeakMap(), trace };
1120
+ const tracedSearch = createSearch(config, traced, getVariableOrder);
1121
+ if (!tracedSearch) return result;
1122
+ const replayed: string[] = [];
1123
+ output.replayed = replayed;
1124
+ valueSources.current = new WeakMap();
1125
+ const replayedStack = getReplayedCallStack(() => replay(tracedSearch, traced), trace);
1126
+ valueSources.current = undefined;
1127
+ output.replayed = undefined;
1128
+ return {
1129
+ ...result,
1130
+ failure: { ...result.failure, replay: { output: replayed, ...replayedStack, isBeforeError } },
1131
+ };
1132
+ };
1133
+ // TLC fingerprints a state outside CallStackTool, so a failure leaves the stack empty.
1134
+ const fingerprintReplayed = (state: Value[], traced: Environment) => {
1135
+ try {
1136
+ getStateHash(getFingerprintState(state));
1137
+ } catch (error) {
1138
+ if (traced.trace) traced.trace.length = 0;
1139
+ throw error;
1140
+ }
1141
+ };
1142
+ // TLC checks every initial state again, as when it first generated them.
1143
+ const replayInitialStates = (result: CheckResult) =>
1144
+ replayFailure(result, (tracedSearch, traced) => {
1145
+ if (spec.init === undefined) return;
1146
+ forEachInitialState(
1147
+ spec.init,
1148
+ traced,
1149
+ (state) => {
1150
+ if (tracedSearch.satisfiesConstraints(state)) fingerprintReplayed(state, traced);
1151
+ return (
1152
+ tracedSearch.findViolatedInvariant(state) !== undefined ||
1153
+ tracedSearch.findFailedInitialPredicate(state) !== undefined
1154
+ );
1155
+ },
1156
+ spec.scope,
1157
+ );
1158
+ });
1159
+ // TLC rebuilds the behavior up to the state it expanded before it replays the step.
1160
+ const rebuildBehavior = (index: number): void => {
1161
+ const parent = parents[index];
1162
+ if (parent === -1) {
1163
+ getSpecInitialStates();
1164
+ return;
1165
+ }
1166
+ rebuildBehavior(parent);
1167
+ getLabel(parent, states[parent], states[index]);
1168
+ };
1169
+ // TLC generates the successors of each action before it checks them. It checks the invariants
1170
+ // only of a successor outside the model, since it has seen the others.
1171
+ const replaySuccessors = (result: CheckResult, index: number) =>
1172
+ replayFailure(result, (tracedSearch, traced) => {
1173
+ rebuildBehavior(index);
1174
+ const state = states[index];
1175
+ nextActions.value ??= getNextActions(config, environment, specification.instanceActions);
1176
+ nextActions.value.find((action) =>
1177
+ getSuccessors(action.expression, state, traced, action.scope).some((successor) => {
1178
+ const isInModel =
1179
+ tracedSearch.satisfiesConstraints(successor.state) &&
1180
+ tracedSearch.satisfiesActionConstraints(state, successor.state);
1181
+ if (isInModel) fingerprintReplayed(successor.state, traced);
1182
+ return (
1183
+ (!isInModel && tracedSearch.findViolatedInvariant(successor.state) !== undefined) ||
1184
+ tracedSearch.findViolatedActionProperty(state, successor.state) !== undefined
1185
+ );
1186
+ }),
1187
+ );
1188
+ });
964
1189
  const isReducing = config.view !== undefined || config.symmetry !== undefined;
1190
+ const tlcFingerprints: number[] = [];
1191
+ const liveGraph: LiveGraph = {
1192
+ getFingerprint: (index) =>
1193
+ (tlcFingerprints[index] ??= Number(BigInt.asIntN(32, runtime.getFingerprint(states[index])))),
1194
+ getSuccessors: (state) => {
1195
+ const successors: LiveSuccessor[] = [];
1196
+ if (spec.next === undefined) return successors;
1197
+ forEachSuccessor(
1198
+ spec.next,
1199
+ state,
1200
+ environment,
1201
+ (successor) => {
1202
+ canonicalizeState(successor.state);
1203
+ const isInModel =
1204
+ search.satisfiesConstraints(successor.state, state) &&
1205
+ search.satisfiesActionConstraints(state, successor.state);
1206
+ if (!isInModel) return false;
1207
+ const fingerprintState = getFingerprintState(successor.state);
1208
+ const index = findStateIndex(getStateHash(fingerprintState), fingerprintState);
1209
+ successors.push({ index, state: successor.state });
1210
+ return false;
1211
+ },
1212
+ spec.scope,
1213
+ );
1214
+ return successors;
1215
+ },
1216
+ };
965
1217
  const liveness = withLivenessExitCode(() =>
966
- createLivenessChecker(search.properties.liveness, spec.temporals, environment),
1218
+ createLivenessChecker(search.properties.liveness, spec.temporals, environment, liveGraph),
967
1219
  );
968
1220
  const isCanonicalizedFirst = search.isSymmetric || liveness !== undefined;
969
1221
 
@@ -972,7 +1224,9 @@ export const checkSequentially = (options: CheckOptions): CheckResult => {
972
1224
  const parents: number[] = [];
973
1225
  const actions: (string | undefined)[] = [];
974
1226
  const depths: number[] = [];
975
- const buckets = new Map<number, number | number[]>();
1227
+ // A Map holds at most 2^24 entries, so an open-addressing table keeps each seen state's hash
1228
+ // and its index plus one side by side, probed by the hash.
1229
+ const seen = { slots: new Int32Array(1 << 17), size: 0, shift: 16 };
976
1230
  const canonicalizeState = createCanonicalizer();
977
1231
 
978
1232
  const toRecord = (state: Value[]): Record<string, Value> =>
@@ -985,11 +1239,16 @@ export const checkSequentially = (options: CheckOptions): CheckResult => {
985
1239
  position: number,
986
1240
  loopStart: number | undefined,
987
1241
  ) => {
988
- const state = steps[position].state;
989
- const next = (steps[position + 1] ?? steps[loopStart ?? position]).state;
990
1242
  // TLC evaluates TLCGet("level") and Trace in an alias at the state's position in the trace.
991
1243
  runtime.getLevel = () => position + 1;
992
1244
  runtime.getBehavior = () => steps.slice(0, position + 1).map((step) => step.state);
1245
+ return evaluateAlias(
1246
+ alias,
1247
+ steps[position].state,
1248
+ (steps[position + 1] ?? steps[loopStart ?? position]).state,
1249
+ );
1250
+ };
1251
+ const evaluateAlias = (alias: string, state: Value[], next: Value[] | undefined) => {
993
1252
  try {
994
1253
  const body = getConfigDefinition("alias", alias, environment).body;
995
1254
  const value = evaluate(createIdentifier(alias), getContext(environment, state, next));
@@ -1091,7 +1350,17 @@ export const checkSequentially = (options: CheckOptions): CheckResult => {
1091
1350
  trace: TraceStep[],
1092
1351
  initialState?: Value[],
1093
1352
  failureOutDegrees?: number[],
1094
- ) => {
1353
+ ): CheckResult => {
1354
+ // TLC exits with 255 on a stack overflow while it computes next states, and prints the
1355
+ // behavior up to the state it was expanding.
1356
+ if (isStackOverflow(error)) {
1357
+ return current.isExpanding
1358
+ ? toFailure(
1359
+ setExitCode(new TlaEvaluationError(STACK_OVERFLOW), EXIT_STATUS.error),
1360
+ getStateTrace(current.index),
1361
+ )
1362
+ : toFailure(new TlaEvaluationError(STACK_OVERFLOW), trace, initialState);
1363
+ }
1095
1364
  if (!(error instanceof TlaEvaluationError)) throw error;
1096
1365
  return {
1097
1366
  ...createResult("error", undefined, {
@@ -1104,7 +1373,7 @@ export const checkSequentially = (options: CheckOptions): CheckResult => {
1104
1373
  outDegrees: failureOutDegrees,
1105
1374
  };
1106
1375
  };
1107
- const getPathTrace = (path: number[], loopStart?: number) => {
1376
+ const getPathSteps = (path: number[], loopStart?: number) => {
1108
1377
  const steps = getPathStates(path, NEXT_RECOVERY_FAILURE);
1109
1378
  const last = steps[steps.length - 1].state;
1110
1379
  const isClosed =
@@ -1113,7 +1382,7 @@ export const checkSequentially = (options: CheckOptions): CheckResult => {
1113
1382
  loopStart === path.length - 1 ||
1114
1383
  findSuccessorWithFingerprint(last, path[loopStart]) !== undefined;
1115
1384
  if (!isClosed) throw new TlaEvaluationError(NEXT_RECOVERY_FAILURE);
1116
- return toTrace(steps, path, loopStart);
1385
+ return steps;
1117
1386
  };
1118
1387
  const getStateHash = (state: Value[]) => {
1119
1388
  let hash = 0x811c9dc5;
@@ -1127,19 +1396,35 @@ export const checkSequentially = (options: CheckOptions): CheckResult => {
1127
1396
  }
1128
1397
  return true;
1129
1398
  };
1399
+ const getSlot = (hash: number) => (Math.imul(hash, 0x9e3779b1) >>> seen.shift) << 1;
1130
1400
  const findStateIndex = (hash: number, state: Value[]) => {
1131
- const bucket = buckets.get(hash);
1132
- if (bucket === undefined) return -1;
1133
- if (typeof bucket === "number") {
1134
- return isSameState(fingerprintStates[bucket], state) ? bucket : -1;
1401
+ const mask = seen.slots.length - 1;
1402
+ for (let slot = getSlot(hash); ; slot = (slot + 2) & mask) {
1403
+ const entry = seen.slots[slot + 1];
1404
+ if (entry === 0) return -1;
1405
+ if (seen.slots[slot] === hash && isSameState(fingerprintStates[entry - 1], state)) {
1406
+ return entry - 1;
1407
+ }
1135
1408
  }
1136
- return bucket.find((index) => isSameState(fingerprintStates[index], state)) ?? -1;
1409
+ };
1410
+ const insertSeen = (hash: number, entry: number) => {
1411
+ const mask = seen.slots.length - 1;
1412
+ let slot = getSlot(hash);
1413
+ while (seen.slots[slot + 1] !== 0) slot = (slot + 2) & mask;
1414
+ seen.slots[slot] = hash;
1415
+ seen.slots[slot + 1] = entry;
1137
1416
  };
1138
1417
  const markSeen = (hash: number, index: number) => {
1139
- const bucket = buckets.get(hash);
1140
- if (bucket === undefined) buckets.set(hash, index);
1141
- else if (typeof bucket === "number") buckets.set(hash, [bucket, index]);
1142
- else bucket.push(index);
1418
+ seen.size++;
1419
+ if (seen.size * 4 > seen.slots.length) {
1420
+ const slots = seen.slots;
1421
+ seen.slots = new Int32Array(slots.length * 2);
1422
+ seen.shift--;
1423
+ for (let slot = 0; slot < slots.length; slot += 2) {
1424
+ if (slots[slot + 1] !== 0) insertSeen(slots[slot], slots[slot + 1]);
1425
+ }
1426
+ }
1427
+ insertSeen(hash, index + 1);
1143
1428
  };
1144
1429
  const countDistinctState = (depth: number) => {
1145
1430
  runtime.distinctStates = states.length + 1;
@@ -1165,6 +1450,7 @@ export const checkSequentially = (options: CheckOptions): CheckResult => {
1165
1450
  isExpanding: false,
1166
1451
  candidate: undefined as Value[] | undefined,
1167
1452
  candidateLevel: 0,
1453
+ isFingerprinting: false,
1168
1454
  livenessSource: -1,
1169
1455
  };
1170
1456
  const getPath = (index: number): Value[][] =>
@@ -1179,7 +1465,7 @@ export const checkSequentially = (options: CheckOptions): CheckResult => {
1179
1465
  };
1180
1466
  runtime.getCurrentState = () => (current.index === -1 ? undefined : states[current.index]);
1181
1467
  runtime.setLivenessSource = (index) => {
1182
- current.livenessSource = index;
1468
+ current.livenessSource = index ?? -1;
1183
1469
  };
1184
1470
  runtime.getLevel = (state) => {
1185
1471
  const source = current.livenessSource;
@@ -1190,6 +1476,18 @@ export const checkSequentially = (options: CheckOptions): CheckResult => {
1190
1476
  return current.isExpanding ? depths[current.index] + 1 : 0;
1191
1477
  };
1192
1478
 
1479
+ const getGraphState = (state: Value[], level: number): GraphState => ({
1480
+ fingerprint: BigInt.asIntN(64, runtime.getFingerprint(state)),
1481
+ level,
1482
+ getLabel: () =>
1483
+ formatState(
1484
+ config.alias === undefined
1485
+ ? toRecord(state)
1486
+ : evaluateAlias(config.alias, state, undefined),
1487
+ ),
1488
+ getText: () => formatState(toRecord(state)),
1489
+ });
1490
+
1193
1491
  const visitInitialState = (state: Value[]) => {
1194
1492
  canonicalizeState(state);
1195
1493
  runtime.generatedStates++;
@@ -1206,6 +1504,7 @@ export const checkSequentially = (options: CheckOptions): CheckResult => {
1206
1504
  countDistinctState(1);
1207
1505
  runtime.queueSize++;
1208
1506
  liveness?.addInitialState(states.length, state);
1507
+ stateWriter?.writeInitialState(getGraphState(state, 1));
1209
1508
  }
1210
1509
  const violated = search.findViolatedInvariant(state);
1211
1510
  if (violated) {
@@ -1226,20 +1525,36 @@ export const checkSequentially = (options: CheckOptions): CheckResult => {
1226
1525
  addState(state, fingerprintState, -1, undefined);
1227
1526
  return undefined;
1228
1527
  };
1229
- const visitSuccessor = (index: number, successor: Successor, liveSuccessors: LiveSuccessor[]) => {
1528
+ const visitSuccessor = (
1529
+ index: number,
1530
+ successor: Successor,
1531
+ liveSuccessors: LiveSuccessor[],
1532
+ source: GraphState | undefined,
1533
+ action: SpecAction | undefined,
1534
+ ) => {
1230
1535
  const state = states[index];
1231
1536
  runtime.generatedStates++;
1232
1537
  current.candidate = successor.state;
1233
1538
  current.candidateLevel = depths[index] + 1;
1234
1539
  if (isCanonicalizedFirst) canonicalizeState(successor.state);
1540
+ current.isFingerprinting = true;
1235
1541
  const fingerprintState = getFingerprintState(successor.state);
1236
1542
  const hash = getStateHash(fingerprintState);
1543
+ current.isFingerprinting = false;
1237
1544
  const found = findStateIndex(hash, fingerprintState);
1238
1545
  const isStateInModel = search.satisfiesConstraints(successor.state, state);
1239
1546
  if (isStateInModel) search.trackStatePossible(successor.state);
1240
1547
  const isInModel = isStateInModel && search.satisfiesActionConstraints(state, successor.state);
1241
1548
  if (isInModel) search.trackActionPossible(state, successor.state);
1242
1549
  const existing = isInModel ? found : -1;
1550
+ if (source && isInModel) {
1551
+ stateWriter?.writeSuccessor(
1552
+ source,
1553
+ getGraphState(successor.state, depths[index] + 1),
1554
+ existing !== -1,
1555
+ action && { name: action.name, signature: getActionSignature(action) },
1556
+ );
1557
+ }
1243
1558
  if (existing !== -1 && liveness) {
1244
1559
  const stored = states[existing];
1245
1560
  const isStored = stored.every((value, position) => value === successor.state[position]);
@@ -1297,10 +1612,22 @@ export const checkSequentially = (options: CheckOptions): CheckResult => {
1297
1612
  spec.scope,
1298
1613
  );
1299
1614
  } catch (error) {
1300
- return toFailure(error, []);
1615
+ if (!(error instanceof TlaIllegalStateError))
1616
+ return replayInitialStates(toFailure(error, []));
1617
+ // TLC prints an illegal initial state with null for each variable it leaves undefined, and
1618
+ // stops before it prints the statistics.
1619
+ const illegal = toFailure(
1620
+ error,
1621
+ [],
1622
+ error.state.map((value) => value ?? createModelValue("null")),
1623
+ );
1624
+ return {
1625
+ ...illegal,
1626
+ failure: illegal.failure && { ...illegal.failure, isWithoutStatistics: true },
1627
+ };
1301
1628
  }
1302
1629
  }
1303
- if (outcome.result) return outcome.result;
1630
+ if (outcome.result) return replayInitialStates(outcome.result);
1304
1631
 
1305
1632
  const next = spec.next;
1306
1633
  if (next === undefined) {
@@ -1311,23 +1638,58 @@ export const checkSequentially = (options: CheckOptions): CheckResult => {
1311
1638
  }
1312
1639
  return createSuccess();
1313
1640
  }
1641
+ // TLC labels and colors an edge of the -dump state graph by the action that generated it. When
1642
+ // the graph names its edges, the search generates successors action by action, as TLC does.
1643
+ const isNamingEdges = Boolean(
1644
+ options.dump?.dot && (options.dump.actionLabels || options.dump.colorize),
1645
+ );
1646
+ const forEachActionSuccessor = (
1647
+ state: Value[],
1648
+ onSuccessor: (successor: Successor, action: SpecAction | undefined) => boolean,
1649
+ ) => {
1650
+ if (!isNamingEdges) {
1651
+ return forEachSuccessor(
1652
+ next,
1653
+ state,
1654
+ environment,
1655
+ (successor) => onSuccessor(successor, undefined),
1656
+ spec.scope,
1657
+ );
1658
+ }
1659
+ nextActions.value ??= getNextActions(config, environment, specification.instanceActions);
1660
+ const progress = { isStopped: false };
1661
+ return nextActions.value.reduce((count, action) => {
1662
+ if (progress.isStopped) return count;
1663
+ return (
1664
+ count +
1665
+ forEachSuccessor(
1666
+ action.expression,
1667
+ state,
1668
+ environment,
1669
+ (successor) => {
1670
+ progress.isStopped = onSuccessor(successor, action);
1671
+ return progress.isStopped;
1672
+ },
1673
+ action.scope,
1674
+ )
1675
+ );
1676
+ }, 0);
1677
+ };
1314
1678
  const expandState = (index: number) => {
1315
1679
  const state = states[index];
1316
1680
  const liveSuccessors: LiveSuccessor[] = [];
1317
- const successorCount = forEachSuccessor(
1318
- next,
1319
- state,
1320
- environment,
1321
- (successor) => {
1322
- try {
1323
- outcome.result = visitSuccessor(index, successor, liveSuccessors);
1324
- } catch (error) {
1325
- outcome.result = toFailure(error, getTrace(index, successor));
1326
- }
1327
- return outcome.result !== undefined;
1328
- },
1329
- spec.scope,
1330
- );
1681
+ const source = stateWriter && getGraphState(state, depths[index]);
1682
+ const successorCount = forEachActionSuccessor(state, (successor, action) => {
1683
+ try {
1684
+ outcome.result = visitSuccessor(index, successor, liveSuccessors, source, action);
1685
+ } catch (error) {
1686
+ // TLC reports a successor it cannot fingerprint as a failure of the state it expands.
1687
+ if (current.isFingerprinting) throw error;
1688
+ const failure = toFailure(error, getTrace(index, successor));
1689
+ outcome.result = isStackOverflow(error) ? failure : replaySuccessors(failure, index);
1690
+ }
1691
+ return outcome.result !== undefined;
1692
+ });
1331
1693
  current.isExpanding = false;
1332
1694
  if (outcome.result) return outcome.result;
1333
1695
  if (successorCount === 0 && config.checkDeadlock) {
@@ -1335,32 +1697,78 @@ export const checkSequentially = (options: CheckOptions): CheckResult => {
1335
1697
  }
1336
1698
  try {
1337
1699
  const accepted = liveness?.addState(index, state, liveSuccessors);
1338
- current.livenessSource = -1;
1339
- if (!accepted) return undefined;
1700
+ if (!liveness || !accepted) return undefined;
1701
+ const steps = getPathSteps(accepted);
1702
+ const properties = liveness.getViolatedProperties(
1703
+ steps.map((step) => step.state),
1704
+ steps.length - 1,
1705
+ );
1340
1706
  return reportViolation("property-violation", {
1341
- name: accepted.name,
1342
- trace: getPathTrace(accepted.path),
1707
+ name: properties[0],
1708
+ properties,
1709
+ trace: toTrace(steps, accepted),
1343
1710
  });
1344
1711
  } catch (error) {
1345
- return toFailure(error, getStateTrace(index), undefined, getPartialOutDegrees());
1712
+ return replayFailure(
1713
+ toFailure(toNextStateError(error), getStateTrace(index), undefined, getPartialOutDegrees()),
1714
+ (_, traced) =>
1715
+ createLivenessChecker(
1716
+ search.properties.liveness,
1717
+ spec.temporals,
1718
+ traced,
1719
+ liveGraph,
1720
+ )?.addState(index, state, liveSuccessors),
1721
+ true,
1722
+ );
1346
1723
  }
1347
1724
  };
1348
- const reportLasso = (lasso: Lasso) => {
1725
+ // TLC names the action when the next-state relation has more than one, and prints the
1726
+ // incomplete successor with null for each variable it leaves undefined.
1727
+ const reportIncompleteSuccessor = (error: TlaIncompleteStateError, index: number) => {
1728
+ nextActions.value ??= getNextActions(config, environment, specification.instanceActions);
1729
+ const actions = nextActions.value;
1730
+ const action =
1731
+ actions.length === 1 ? actions[0] : actions.find((item) => item.name === error.action);
1732
+ const variables = `variable${error.missing.length > 1 ? "s are" : " is"} not defined: ${error.missing.join(", ")}.\n`;
1733
+ runtime.generatedStates++;
1734
+ return toFailure(
1735
+ actions.length === 1
1736
+ ? error
1737
+ : new TlaEvaluationError(
1738
+ `Successor state is not completely specified by action ${error.action} of the next-state relation. The following ${variables}`,
1739
+ ),
1740
+ [
1741
+ ...getStateTrace(index),
1742
+ {
1743
+ action: error.action,
1744
+ label: action && getActionLabel(action),
1745
+ state: toRecord(error.state.map((value) => value ?? createModelValue("null"))),
1746
+ },
1747
+ ],
1748
+ );
1749
+ };
1750
+ // TLC names the properties and the step back into the cycle from the states it prints.
1751
+ const reportLasso = (checker: LivenessChecker, lasso: Lasso) => {
1349
1752
  const path = [...lasso.prefix, ...lasso.cycle];
1350
- const trace = getPathTrace(path, lasso.prefix.length);
1351
- const back = path[lasso.prefix.length];
1753
+ const loopStart = lasso.prefix.length;
1754
+ const steps = getPathSteps(path, loopStart);
1755
+ const trace = toTrace(steps, path, loopStart);
1756
+ const properties = checker.getViolatedProperties(
1757
+ steps.map((step) => step.state),
1758
+ loopStart,
1759
+ );
1760
+ const back = path[loopStart];
1352
1761
  const last = path[path.length - 1];
1762
+ const lastState = steps[steps.length - 1].state;
1353
1763
  const loopLabel =
1354
- back === last ? undefined : withoutOutput(() => getLabel(last, states[last], states[back]));
1764
+ back === last ? undefined : withoutOutput(() => getLabel(last, lastState, states[back]));
1355
1765
  return reportViolation(
1356
1766
  "liveness-violation",
1357
- { name: lasso.name, trace, loopStart: lasso.prefix.length, loopLabel },
1767
+ { name: properties[0], properties, trace, loopStart, loopLabel },
1358
1768
  () =>
1359
1769
  back === last
1360
1770
  ? trace[trace.length - 1].action
1361
- : getTraceSuccessors(states[last]).find((successor) =>
1362
- isSameState(successor.state, states[back]),
1363
- )?.action,
1771
+ : findSuccessorWithFingerprint(lastState, back)?.action,
1364
1772
  );
1365
1773
  };
1366
1774
  const isPeriodic = liveness !== undefined && options.livenessCheck !== "final";
@@ -1373,11 +1781,9 @@ export const checkSequentially = (options: CheckOptions): CheckResult => {
1373
1781
  if (!isGrown || periodic.time > (now - startedAt) * LIVENESS_RATIO) return undefined;
1374
1782
  periodic.size = expanded;
1375
1783
  const lasso = liveness?.findViolation();
1376
- current.livenessSource = -1;
1377
1784
  periodic.time += performance.now() - now;
1378
1785
  return lasso;
1379
1786
  };
1380
- setNextStatePhase(true);
1381
1787
  for (let index = 0; index < states.length && !runtime.isStopped; index++) {
1382
1788
  current.index = index;
1383
1789
  current.candidate = undefined;
@@ -1386,22 +1792,28 @@ export const checkSequentially = (options: CheckOptions): CheckResult => {
1386
1792
  try {
1387
1793
  outcome.result = expandState(index);
1388
1794
  } catch (error) {
1389
- outcome.result = toFailure(error, getStateTrace(index));
1795
+ const failure =
1796
+ error instanceof TlaIncompleteStateError
1797
+ ? reportIncompleteSuccessor(error, index)
1798
+ : toFailure(toNextStateError(error), getStateTrace(index));
1799
+ outcome.result =
1800
+ error instanceof TlaIncompleteStateError || isStackOverflow(error)
1801
+ ? failure
1802
+ : replaySuccessors(failure, index);
1390
1803
  }
1391
1804
  if (outcome.result) return outcome.result;
1392
1805
  outDegrees[getOutDegreeBucket()]++;
1393
1806
  expansion.newStates = 0;
1394
1807
  if (isPeriodic && performance.now() >= periodic.at) {
1395
1808
  const lasso = findPeriodicViolation(index + 1);
1396
- if (lasso) return reportLasso(lasso);
1809
+ if (liveness && lasso) return reportLasso(liveness, lasso);
1397
1810
  }
1398
1811
  }
1399
1812
 
1400
1813
  current.index = -1;
1401
1814
  current.candidate = undefined;
1402
1815
  const lasso = liveness?.findViolation();
1403
- current.livenessSource = -1;
1404
- if (lasso) return reportLasso(lasso);
1816
+ if (liveness && lasso) return reportLasso(liveness, lasso);
1405
1817
 
1406
1818
  const postconditionViolation = search.findPostconditionViolation();
1407
1819
  if (postconditionViolation) {