tla-ts 0.0.10-dev.28c823e4b → 0.0.10-dev.b4a856304

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 (68) hide show
  1. package/dist/index.cjs +1 -1
  2. package/dist/index.d.cts +0 -34
  3. package/dist/index.d.ts +0 -34
  4. package/dist/index.js +1 -1
  5. package/dist/parallel-worker.cjs +1 -1
  6. package/dist/parallel-worker.js +1 -1
  7. package/dist/prove.cjs +43 -43
  8. package/dist/prove.js +47 -47
  9. package/dist/run.cjs +30 -30
  10. package/dist/run.js +33 -33
  11. package/dist/transfer.cjs +38 -38
  12. package/dist/transfer.js +39 -39
  13. package/package.json +1 -1
  14. package/src/ast.ts +5 -0
  15. package/src/bags.ts +5 -2
  16. package/src/builtins.ts +8 -1
  17. package/src/check.ts +193 -128
  18. package/src/cli/run.ts +2 -0
  19. package/src/cli/runtime-invariants.ts +7 -8
  20. package/src/cli/shared.ts +4 -0
  21. package/src/cli/tlc-arguments.ts +30 -24
  22. package/src/cli/tlc-usage.ts +3 -2
  23. package/src/evaluate.ts +102 -26
  24. package/src/java-overrides.ts +9 -4
  25. package/src/json-reader.ts +2 -1
  26. package/src/json.ts +11 -4
  27. package/src/levels.ts +15 -7
  28. package/src/lexer.ts +83 -72
  29. package/src/liveness-checker.ts +106 -77
  30. package/src/liveness.ts +34 -10
  31. package/src/parallel.ts +33 -26
  32. package/src/parser.ts +226 -163
  33. package/src/pcal/ast.ts +65 -53
  34. package/src/pcal/parse.ts +191 -144
  35. package/src/pcal/tokenize.ts +115 -91
  36. package/src/pcal/translate.ts +98 -83
  37. package/src/pcal/validate.ts +50 -48
  38. package/src/pretty-print.ts +6 -6
  39. package/src/randomization.ts +4 -1
  40. package/src/resolve.ts +70 -12
  41. package/src/runtime.ts +18 -11
  42. package/src/sany/builtins.ts +3 -1
  43. package/src/sany/generator.ts +127 -74
  44. package/src/sany/levels.ts +9 -5
  45. package/src/sany/lexer.ts +44 -40
  46. package/src/sany/linter.ts +1 -0
  47. package/src/search.ts +1 -1
  48. package/src/simulate.ts +59 -50
  49. package/src/spec-description.ts +34 -23
  50. package/src/standard-definitions.ts +3 -0
  51. package/src/standard-modules.ts +12 -1
  52. package/src/state-graph.ts +8 -1
  53. package/src/subexpressions.ts +47 -38
  54. package/src/successors.ts +35 -14
  55. package/src/symmetry.ts +19 -4
  56. package/src/tlc/fingerprint.ts +21 -15
  57. package/src/tlc/jar-data.ts +1 -0
  58. package/src/tlc/messages.ts +21 -2
  59. package/src/tlc/order.ts +38 -20
  60. package/src/tlc/random.ts +30 -18
  61. package/src/tlc/replay.ts +33 -13
  62. package/src/tlc/summary.ts +45 -36
  63. package/src/tlc/tlc-operators.ts +14 -4
  64. package/src/tlc/tlcext-operators.ts +15 -11
  65. package/src/tlc/trace-spec.ts +4 -0
  66. package/src/tlc/value-stream.ts +13 -9
  67. package/src/tlc/version.ts +1 -0
  68. package/src/values.ts +181 -74
package/src/evaluate.ts CHANGED
@@ -10,6 +10,7 @@ import {
10
10
  type NumberExpression,
11
11
  type OperatorParam,
12
12
  type RecordField,
13
+ type SourceRange,
13
14
  } from "./ast";
14
15
  import { getKindString } from "./builtins";
15
16
  import {
@@ -17,7 +18,6 @@ import {
17
18
  TlaEvaluationError,
18
19
  TlaSetBoundError,
19
20
  TlaUnassignedError,
20
- formatRange,
21
21
  } from "./errors";
22
22
  import { EXIT_STATUS, setExitCode } from "./exit-codes";
23
23
  import { generateEvaluator } from "./codegen";
@@ -103,7 +103,9 @@ export interface Builtin {
103
103
  evaluateUnary: ((value: Value) => Value) | undefined;
104
104
  evaluateBinary: ((left: Value, right: Value) => Value) | undefined;
105
105
  isStateLevel?: boolean;
106
+ // Whether TLC takes an application for a constant one although its value depends on the state.
106
107
  isLevelConstant?: boolean;
108
+ // TLC's minLevel of ActionLevel for a Java override.
107
109
  isActionLevel?: boolean;
108
110
  isLazy?: boolean;
109
111
  }
@@ -125,11 +127,14 @@ export interface Thunk {
125
127
  state: State | undefined;
126
128
  next: State | undefined;
127
129
  cache: Value | undefined;
130
+ // Whether the value may stream until TLC caches it, so the thunk caches only a settled value.
128
131
  isStreamed: boolean;
132
+ // Whether the thunk dropped its scope after caching a value that holds in every state.
129
133
  isReleased?: boolean;
130
134
  }
131
135
 
132
136
  type Binding =
137
+ // A literal argument keeps its expression, which TLC binds lazily like any other.
133
138
  | { kind: "Value"; value: Value; argument?: Expression }
134
139
  | Thunk
135
140
  | { kind: "Operator"; operator: Operator };
@@ -150,7 +155,9 @@ export interface Environment {
150
155
  variables: string[];
151
156
  variableIndex: Map<string, number>;
152
157
  facts: DefinitionFacts;
158
+ // TLC evaluates a constant definition it failed to compute at startup where the spec uses it.
153
159
  startupValues: (Value | undefined)[];
160
+ // SANY wraps the body of each of these INSTANCE copies in its substitutions.
154
161
  substitutedDefinitions: Set<Definition>;
155
162
  instanceParams: Set<OperatorParam>;
156
163
  evaluators: WeakMap<Expression, Evaluator>;
@@ -162,20 +169,26 @@ export interface Environment {
162
169
 
163
170
  export interface CallStack {
164
171
  expressions: Expression[];
172
+ // TLC stops popping the stack once an evaluation fails, so it keeps where the failure occurred.
165
173
  isFrozen: boolean;
166
174
  sources: WeakMap<ObjectValue, Expression>;
167
175
  values: WeakMap<Expression, Value>;
176
+ // Tells a failure of an operand from one of the method that computes the operator.
168
177
  failures: WeakMap<Error, Expression>;
169
178
  fingerprint?: FingerprintFailure;
170
179
  }
171
180
 
172
181
  export interface FingerprintFailure {
182
+ // The sources of the values whose methods failed, outermost first.
173
183
  sources: Expression[];
174
184
  reason: string;
175
185
  }
176
186
 
187
+ // The operators whose value TLC's CallStackTool gives a source.
177
188
  const SOURCED_OPERATORS = new Set(["SUBSET", "UNION", "DOMAIN", "\\cup", "\\cap", "\\"]);
178
189
 
190
+ // CallStackTool returns these lazy values without their source, and a function TLC builds
191
+ // from a FcnLambdaValue has none.
179
192
  const SOURCED_KINDS = new Set<Expression["kind"]>([
180
193
  "SetEnumeration",
181
194
  "SetFilter",
@@ -191,6 +204,7 @@ const isSourced = (expression: Expression) =>
191
204
  SOURCED_KINDS.has(expression.kind) ||
192
205
  (expression.kind === "Apply" && SOURCED_OPERATORS.has(expression.operator));
193
206
 
207
+ // The operand whose Java method computes the operator, such as S in e \in S or f in f[e].
194
208
  const getReceiver = (expression: Expression, values: CallStack["values"]) => {
195
209
  if (expression.kind === "FunctionApplication" || expression.kind === "Except") {
196
210
  return expression.function;
@@ -211,6 +225,7 @@ export interface Context {
211
225
  scope: Scope | undefined;
212
226
  state: State | undefined;
213
227
  next: State | undefined;
228
+ // TLC's EvalControl.KeepLazy, so a function constructor within an applied function stays lazy.
214
229
  isKeepLazy?: boolean;
215
230
  }
216
231
 
@@ -234,6 +249,9 @@ const EXCEPT_AT = "@";
234
249
  export const describeLocation = (expression: Expression) =>
235
250
  `line ${expression.location.line}, column ${expression.location.column}`;
236
251
 
252
+ export const formatRange = (range: SourceRange) =>
253
+ `line ${range.start.line}, col ${range.start.column} to line ${range.end.line}, col ${range.end.column} of module ${range.module}`;
254
+
237
255
  export const describeRange = (expression: Expression) => {
238
256
  const range = expression.location.range;
239
257
  return range ? formatRange(range) : describeLocation(expression);
@@ -251,6 +269,7 @@ const createTemporalFormulaError = (form: string, expression: Expression) =>
251
269
  `TLC encountered a temporal formula (${form}) when evaluating a predicate or action.\n${describeRange(expression)}`,
252
270
  );
253
271
 
272
+ // SANY prints a numeral as written and any other expression by its location.
254
273
  export const describeNode = (expression: Expression) =>
255
274
  expression.kind === "Number"
256
275
  ? (expression.text ?? String(expression.value))
@@ -261,6 +280,7 @@ export const createConditionError = (expression: Expression, value: Value) =>
261
280
  `A non-boolean expression (${getKindString(value)}) was used as the condition of an IF.\n${describeRange(expression)}`,
262
281
  );
263
282
 
283
+ // TLC words the error differently for an infix chain of /\ or \/ and for a bulleted list.
264
284
  export const createJunctionError = (
265
285
  expression: Expression & { kind: "And" | "Or" },
266
286
  index: number,
@@ -281,6 +301,7 @@ export const createJunctionError = (
281
301
  );
282
302
  };
283
303
 
304
+ // TLC selects a field from the function it converts a non-record to, which keeps a tuple's domain.
284
305
  export const getFieldSelector = (expression: Expression & { kind: "FieldAccess" }) => {
285
306
  const field = expression.field;
286
307
  const describeMissing = (record: Value) =>
@@ -295,6 +316,7 @@ export const getFieldSelector = (expression: Expression & { kind: "FieldAccess"
295
316
  }
296
317
  const functionClass = getFunctionClass(value);
297
318
  if (functionClass === "tuple") throw createNonIntegerKeyError(field);
319
+ // Only TLC's RecordValue names the field it lacks, and TLC enumerates a FcnLambdaValue first.
298
320
  return applyFunction(
299
321
  value.kind === "LazyFunction" ? toFiniteFunction(value) : value,
300
322
  field,
@@ -303,6 +325,7 @@ export const getFieldSelector = (expression: Expression & { kind: "FieldAccess"
303
325
  };
304
326
  };
305
327
 
328
+ // TLC 1.7.4 words what a tuple or a record lacks differently.
306
329
  export const getMissingArgumentDescriber = (version: TlcVersion | undefined) =>
307
330
  version === "1.7.4"
308
331
  ? (functionValue: Value, argument: Value) =>
@@ -330,6 +353,7 @@ export const getSubsetOperator =
330
353
  : builtin.evaluate([left, right]);
331
354
  };
332
355
 
356
+ // TLC rejects a decimal, or an integer literal too big for it, while it processes the spec.
333
357
  export const createRealNumberError = (expression: DecimalExpression) =>
334
358
  setExitCode(
335
359
  new TlaEvaluationError(`TLC can't handle real numbers.\n${expression.text}`),
@@ -350,6 +374,8 @@ export const createUnassignedError = (name: string, expression: Expression) =>
350
374
  name,
351
375
  );
352
376
 
377
+ // TLC reads the subscript of <<A>>_v in the successor as a state of its own, and after 1.7.4
378
+ // names the fairness condition when A leaves a variable of v unassigned.
353
379
  export const toUnspecifiedSubscriptError = (error: unknown, version: TlcVersion | undefined) =>
354
380
  error instanceof TlaUnassignedError && version !== "1.7.4"
355
381
  ? new TlaEvaluationError(
@@ -385,6 +411,7 @@ export const bindPattern = (scope: Scope | undefined, pattern: BoundPattern, val
385
411
  );
386
412
  };
387
413
 
414
+ // Tool#evalAppl checks that it applies a function before it evaluates the argument.
388
415
  export const expectFunction = (value: Value, application: Expression) => {
389
416
  if (isFunctionValue(value)) return value;
390
417
  throw new TlaEvaluationError(
@@ -475,9 +502,11 @@ const getBoundExplanation = (set: Value, text: string) => {
475
502
  return undefined;
476
503
  };
477
504
 
505
+ // TLC enumerates every set but its Java ones, so any other set fails as its own class does.
478
506
  const checkEnumerable = (set: Value, expression: Expression, version: TlcVersion) => {
479
507
  if (!isSetValue(set) || isOverriddenSet(set)) {
480
508
  const text = formatValue(set);
509
+ // TLC 1.7.4 doesn't explain why it can't enumerate a set.
481
510
  const explanation = version === "1.7.4" ? undefined : getBoundExplanation(set, text);
482
511
  throw new TlaEvaluationError(
483
512
  explanation === undefined
@@ -493,12 +522,14 @@ const getEnumeratedElements = (set: Value, expression: Expression, version: TlcV
493
522
  return getLazySubsets(set) ?? getNormalizedSetElements(set);
494
523
  };
495
524
 
525
+ // TLC 1.7.4 streams a lazy set's elements, where later versions normalize the set first.
496
526
  export const getContextElements = (set: Value, expression: Expression, version: TlcVersion) => {
497
527
  if (version !== "1.7.4") return getEnumeratedElements(set, expression, version);
498
528
  checkEnumerable(set, expression, version);
499
529
  return getLazySubsets(set) ?? getStreamedElements(set);
500
530
  };
501
531
 
532
+ // Like TLC, keep an interval so a quantifier can stop at a witness in 1..2000000000 early.
502
533
  const getKeptInterval = (set: Value) => {
503
534
  if (typeof set !== "object" || set.kind !== "Interval") return undefined;
504
535
  getCardinality(set);
@@ -522,6 +553,7 @@ const someElement = (
522
553
  return false;
523
554
  };
524
555
 
556
+ // The names of one bound, as in \A x, y \in S, share its set, which TLC evaluates once.
525
557
  export const mapBoundSets = <Result>(bounds: Bound[], map: (set: Expression) => Result) =>
526
558
  bounds.reduce<Result[]>((results, bound, index) => {
527
559
  results.push(
@@ -614,7 +646,8 @@ export const bindLazyArguments = (
614
646
  typeof value.domain === "object" && value.domain.kind === "ProductSet"
615
647
  ? value.domain.factors
616
648
  : [];
617
- // Deviation from TLC: FcnLambdaValue#apply indexes past an argument tuple shorter than the bounds and ignores a longer one.
649
+ // FcnLambdaValue#apply indexes past an argument tuple shorter than the bounds and ignores one
650
+ // longer, where this rejects the list.
618
651
  const createListError = () =>
619
652
  new TlaEvaluationError(
620
653
  `In applying the function\n${prettyPrint(formatValue(value))},\nthe argument list is:\n${prettyPrint(formatValue(argument))}\nwhich does not match its formal parameter.\n`,
@@ -646,6 +679,7 @@ export const bindLazyArguments = (
646
679
  return bindArgument(bounds, lambda.scope, argument);
647
680
  };
648
681
 
682
+ // TLC prints a function it can't enumerate with only the first name of a group such as m, n.
649
683
  interface LazyFunctionTemplate {
650
684
  parameters: { index: number; name: string }[];
651
685
  body: string;
@@ -714,6 +748,7 @@ const getBoundTupleLengths = (bounds: Bound[]) =>
714
748
  bound.pattern.kind === "Tuple" ? bound.pattern.names.length : undefined,
715
749
  );
716
750
 
751
+ // The function constructor of a definition, which SANY locates at the whole definition.
717
752
  const getDefinitionSource = (definition: FunctionDefinition): Expression => ({
718
753
  kind: "FunctionConstruction",
719
754
  bounds: definition.bounds,
@@ -759,6 +794,7 @@ const createRecursiveFunction = (
759
794
  return definition.bounds.length === 1 ? markLambdaFunction(rebindable) : rebindable;
760
795
  };
761
796
 
797
+ // TLC computes a constant definition eagerly, so a function over a reducible set is a FcnRcdValue.
762
798
  const toStartupValue = (definition: Definition, value: Value): Value => {
763
799
  if (typeof value !== "object" || getFunctionClass(value) !== "lambda") return value;
764
800
  if (
@@ -773,11 +809,13 @@ const toStartupValue = (definition: Definition, value: Value): Value => {
773
809
  const finite = toFiniteFunction(value);
774
810
  return createSortedFunction(finite.domain, finite.range);
775
811
  } catch (error) {
812
+ // TLC leaves a definition it fails to compute to evaluate where the spec uses it.
776
813
  if (error instanceof TlaEvaluationError) return value;
777
814
  throw error;
778
815
  }
779
816
  };
780
817
 
818
+ // TLC evaluates a function definition that isn't recursive as it does a function constructor.
781
819
  const compileDefinitionBody = (definition: Definition, environment: Environment): Evaluator => {
782
820
  if (definition.kind === "Operator" && definition.params.length > 0) {
783
821
  return () => {
@@ -796,19 +834,19 @@ const getDefinitionEvaluator = (definition: Definition, environment: Environment
796
834
  const compiled = environment.definitionEvaluators.get(definition);
797
835
  if (compiled) return compiled;
798
836
  const body = compileDefinitionBody(definition, environment);
799
- const definitionId = environment.facts.ids.get(definition);
837
+ const id = environment.facts.ids.get(definition);
800
838
  const startupValues = environment.startupValues;
801
839
  const evaluator: Evaluator =
802
- definitionId === undefined
840
+ id === undefined
803
841
  ? (context) => body(withScope(context, undefined))
804
- : (context) => startupValues[definitionId] ?? body(withScope(context, undefined));
842
+ : (context) => startupValues[id] ?? body(withScope(context, undefined));
805
843
  environment.definitionEvaluators.set(definition, evaluator);
806
844
  return evaluator;
807
845
  };
808
846
 
809
847
  export const getStartupValue = (definition: Definition, environment: Environment) => {
810
- const definitionId = environment.facts.ids.get(definition);
811
- return definitionId === undefined ? undefined : environment.startupValues[definitionId];
848
+ const id = environment.facts.ids.get(definition);
849
+ return id === undefined ? undefined : environment.startupValues[id];
812
850
  };
813
851
 
814
852
  export const evaluateStartupDefinitions = (definitions: Definition[], environment: Environment) =>
@@ -817,21 +855,22 @@ export const evaluateStartupDefinitions = (definitions: Definition[], environmen
817
855
  const name = definition.name;
818
856
  if (environment.constants.has(name) || environment.substitutions.has(name)) return;
819
857
  if (!isConstantLevel(definition, environment)) return;
820
- const definitionId = environment.facts.ids.get(definition);
821
- if (definitionId === undefined || environment.startupValues[definitionId] !== undefined) return;
858
+ const id = environment.facts.ids.get(definition);
859
+ if (id === undefined || environment.startupValues[id] !== undefined) return;
822
860
  const context = { environment, scope: undefined, state: undefined, next: undefined };
823
861
  try {
824
862
  const value = environment.runtime.evaluateAtStartup(() =>
825
863
  toStartupValue(definition, compileDefinitionBody(definition, environment)(context)),
826
864
  );
827
865
  markNormalized(value);
828
- environment.startupValues[definitionId] = value;
866
+ environment.startupValues[id] = value;
829
867
  } catch (error) {
830
868
  // TLC swallows whatever the definition throws, a stack overflow included.
831
869
  if (!(error instanceof TlaEvaluationError) && !isStackOverflow(error)) throw error;
832
870
  }
833
871
  });
834
872
 
873
+ // TLC reuses a cached value while each variable the cached state assigns keeps its value.
835
874
  const isStateWithin = (state: State | undefined, cached: State | undefined) => {
836
875
  if (cached === undefined || state === cached) return true;
837
876
  try {
@@ -865,6 +904,8 @@ const forceThunk = (thunk: Thunk, context: Context) => {
865
904
  thunk.state = context.state;
866
905
  thunk.next = context.next;
867
906
  }
907
+ // A value a thunk cached with no state read no variable, so it holds in every state. Releasing
908
+ // its scope frees the evaluations the scope's bindings cached, which a long script keeps alive.
868
909
  if (thunk.cache !== undefined && thunk.state === undefined && thunk.next === undefined) {
869
910
  thunk.scope = undefined;
870
911
  thunk.isReleased = true;
@@ -1013,6 +1054,7 @@ const compileArgumentBinder = (argument: Expression, environment: Environment):
1013
1054
  const binding: Binding = { kind: "Value", value: argument.value, argument };
1014
1055
  return () => binding;
1015
1056
  }
1057
+ // TLC counts an argument where the operator's body evaluates it, under the call.
1016
1058
  const coverage = environment.coverage;
1017
1059
  if (coverage) {
1018
1060
  return (context) => {
@@ -1082,6 +1124,8 @@ interface ReevaluatedDefinitions {
1082
1124
  streamed: ReadonlySet<Definition>;
1083
1125
  }
1084
1126
 
1127
+ // A LET's function definition has one function constructor, as in SANY, so its code compiles once
1128
+ // however often the LET is evaluated.
1085
1129
  const letFunctionConstructions = new WeakMap<FunctionDefinition, Expression>();
1086
1130
 
1087
1131
  const getLetFunctionConstruction = (definition: FunctionDefinition): Expression => {
@@ -1145,6 +1189,7 @@ export const bindDefinitions = (
1145
1189
  isStreamed: reevaluated?.streamed.has(definition) ?? false,
1146
1190
  };
1147
1191
  });
1192
+ // TLC counts a LET definition under the node that encloses the LET.
1148
1193
  const coverage = context.environment.coverage;
1149
1194
  if (coverage && coverage.current !== -1) {
1150
1195
  nodes.forEach((node) => {
@@ -1179,6 +1224,8 @@ const evaluateLocalIdentifier = (name: string, expression: Expression, context:
1179
1224
  throw new TlaEvaluationError(`Unknown identifier ${name} at ${describeLocation(expression)}`);
1180
1225
  };
1181
1226
 
1227
+ // TLC's next-state generator evaluates a LET definition again at each reference, so one that
1228
+ // calls an impure builtin repeats its effects, and a UNION or \cup set starts out uncached.
1182
1229
  export const getReevaluatedDefinitions = (
1183
1230
  definitions: Definition[],
1184
1231
  environment: Environment,
@@ -1220,6 +1267,7 @@ const toNextContext = (context: Context): Context => ({
1220
1267
  isKeepLazy: context.isKeepLazy,
1221
1268
  });
1222
1269
 
1270
+ // TLC evaluates the expression in the current state first.
1223
1271
  const compileUnchanged =
1224
1272
  (evaluator: Evaluator): Evaluator =>
1225
1273
  (context) => {
@@ -1227,6 +1275,7 @@ const compileUnchanged =
1227
1275
  return valuesEqual(current, evaluator(toNextContext(context)));
1228
1276
  };
1229
1277
 
1278
+ // TLC's CallStackTool rebinds the lazy values it returns, so their later evaluation records too.
1230
1279
  const traceEvaluator =
1231
1280
  (
1232
1281
  expression: Expression,
@@ -1282,15 +1331,19 @@ const traceEvaluator =
1282
1331
  }
1283
1332
  };
1284
1333
 
1334
+ // A FingerprintException from a method of a value with a source is headed by each such value
1335
+ // whose method called it in turn, outermost first.
1285
1336
  export const freezeCallStack = (
1286
1337
  callStack: CallStack,
1287
1338
  values: (Value | undefined)[],
1288
1339
  error: unknown,
1289
1340
  ) => {
1341
+ // A set that streams its elements enumerates itself too, so it can appear twice.
1290
1342
  const sources = [...new Set(values)].flatMap((item) => {
1291
1343
  const source = typeof item === "object" ? callStack.sources.get(item) : undefined;
1292
1344
  return source ? [source] : [];
1293
1345
  });
1346
+ // A value with a source raises a FingerprintException even when the stack is frozen already.
1294
1347
  if (sources.length > 0 && error instanceof TlaEvaluationError) {
1295
1348
  if (!callStack.isFrozen) callStack.expressions.push(...sources);
1296
1349
  const inner = callStack.fingerprint;
@@ -1313,6 +1366,7 @@ const headFingerprint = (callStack: CallStack, source: Expression, error: unknow
1313
1366
  };
1314
1367
  };
1315
1368
 
1369
+ // With evaluators of its own, since the environment's evaluators record nothing.
1316
1370
  export const createTracingEnvironment = (environment: Environment): Environment => ({
1317
1371
  ...environment,
1318
1372
  coverage: undefined,
@@ -1328,6 +1382,7 @@ export const createTracingEnvironment = (environment: Environment): Environment
1328
1382
  },
1329
1383
  });
1330
1384
 
1385
+ // A replay that walks into the expression has recorded its frames already.
1331
1386
  const traceFrames =
1332
1387
  (
1333
1388
  expression: Expression,
@@ -1345,6 +1400,8 @@ const traceFrames =
1345
1400
  }
1346
1401
  };
1347
1402
 
1403
+ // TLC counts an evaluation under the node of the expression in the tree of the check it counts,
1404
+ // or, when the tree has none there, under the node it evaluates in.
1348
1405
  const countEvaluator =
1349
1406
  (expression: Expression, evaluator: Evaluator, coverage: Coverage): Evaluator =>
1350
1407
  (context) => {
@@ -1412,9 +1469,11 @@ const compileIdentifier = (
1412
1469
  return () => value;
1413
1470
  }
1414
1471
  if (global?.kind === "Definition") {
1472
+ // The body compiles when first evaluated, as a recursive definition's body refers back to it.
1415
1473
  const definition = global.definition;
1416
- let compiled: Evaluator | undefined;
1417
- return (context) => (compiled ??= getDefinitionEvaluator(definition, environment))(context);
1474
+ const compiled = { reference: undefined as Evaluator | undefined };
1475
+ return (context) =>
1476
+ (compiled.reference ??= getDefinitionEvaluator(definition, environment))(context);
1418
1477
  }
1419
1478
  return (context) => evaluateLocalIdentifier(name, expression, context);
1420
1479
  };
@@ -1494,10 +1553,11 @@ const compileClosureCall = (
1494
1553
  environment: Environment,
1495
1554
  ): Evaluator => {
1496
1555
  const bindArguments = compileArgumentScope(closure, args, environment);
1497
- let body: Evaluator | undefined;
1556
+ // The body compiles when the call is first evaluated, as a recursive operator's body calls it.
1557
+ const compiled = { body: undefined as Evaluator | undefined };
1498
1558
  return (context) => {
1499
- body ??= getEntryEvaluator(closure.body, environment);
1500
- return body({
1559
+ compiled.body ??= getEntryEvaluator(closure.body, environment);
1560
+ return compiled.body({
1501
1561
  environment,
1502
1562
  scope: bindArguments(context),
1503
1563
  state: context.state,
@@ -1545,6 +1605,7 @@ const compileApply = (
1545
1605
  const domain = getDomainOperator(expression);
1546
1606
  return (context) => domain(operand(context));
1547
1607
  }
1608
+ // TLC caches the value of a constant TLCEval argument only where no context binds a name.
1548
1609
  if (global?.kind === "Builtin" && global.name === "TLCEval" && args.length === 1) {
1549
1610
  const isCached =
1550
1611
  !contextualApplications.has(expression) && !isNonconstant(args[0], environment);
@@ -1561,6 +1622,7 @@ const compileApply = (
1561
1622
  return (context) => subset(left(context), right(context));
1562
1623
  }
1563
1624
  if (global?.kind === "Builtin") return compileBuiltinCall(global, args, environment);
1625
+ // TLC refuses action composition unless a Java property enables its incomplete implementation.
1564
1626
  if (expression.operator === "\\cdot" && args.length === 2) {
1565
1627
  return () => {
1566
1628
  throw new TlaEvaluationError(
@@ -1651,6 +1713,7 @@ const getBoundValue = (pattern: BoundPattern, scope: Scope | undefined) => {
1651
1713
  return binding?.kind === "Value" ? binding.value : undefined;
1652
1714
  };
1653
1715
 
1716
+ // TLC keeps a function constructor lazy when it is applied, or is the base of an applied EXCEPT.
1654
1717
  const keptLazyExpressions = new WeakSet<Expression>();
1655
1718
 
1656
1719
  export const keepLazy = (expression: Expression) => {
@@ -1659,6 +1722,8 @@ export const keepLazy = (expression: Expression) => {
1659
1722
  }
1660
1723
  };
1661
1724
 
1725
+ // The names an expression may look up in its scope, or undefined when a subexpression selector may
1726
+ // look up others.
1662
1727
  const scopeNames = new WeakMap<Expression, string[] | undefined>();
1663
1728
 
1664
1729
  const getScopeNames = (expression: Expression) => {
@@ -1676,6 +1741,9 @@ const getScopeNames = (expression: Expression) => {
1676
1741
  return result;
1677
1742
  };
1678
1743
 
1744
+ // The bindings of a scope that names look up, so that a lazy function keeps only those alive and
1745
+ // not the values its other bindings cached. An unnamed node ends the chain, since a TLCEval in the
1746
+ // body sorts its value only where no context binds a name.
1679
1747
  const trimScope = (scope: Scope | undefined, names: string[] | undefined) =>
1680
1748
  names === undefined || scope === undefined
1681
1749
  ? scope
@@ -1689,6 +1757,7 @@ const trimScope = (scope: Scope | undefined, names: string[] | undefined) =>
1689
1757
 
1690
1758
  export const isKeptLazy = (expression: Expression) => keptLazyExpressions.has(expression);
1691
1759
 
1760
+ // Builds the function of a constructor from its evaluated domain.
1692
1761
  export const getFunctionBuilder = (
1693
1762
  expression: Expression & { kind: "FunctionConstruction" },
1694
1763
  environment: Environment,
@@ -1703,7 +1772,8 @@ export const getFunctionBuilder = (
1703
1772
  const name = bound.pattern.name;
1704
1773
  const evaluateAt = (key: Value) =>
1705
1774
  body(withScope(context, bindValue(context.scope, name, key)));
1706
- // TLC sizes the domain and evaluates the body at each element of a domain too large to hold.
1775
+ // TLC sizes the domain, then evaluates the body at each element. A domain too large to hold
1776
+ // the values stays lazy.
1707
1777
  if (isBeyondSetBound(domain)) {
1708
1778
  getCardinality(domain);
1709
1779
  forEachElement(domain, evaluateAt);
@@ -1758,6 +1828,7 @@ export const getFunctionBuilder = (
1758
1828
  ) {
1759
1829
  return createLazy(domain, context);
1760
1830
  }
1831
+ // TLC builds a function lazily unless each bound is reducible, so its body fails where forced.
1761
1832
  const isReducibleDomain =
1762
1833
  bounds.length === 1
1763
1834
  ? isReducibleSet(domain)
@@ -1774,6 +1845,7 @@ export const getFunctionBuilder = (
1774
1845
  }
1775
1846
  }
1776
1847
  if (!callStack) return construct(domain, context);
1848
+ // TLC builds the function in a method of the FcnLambdaValue that CallStackTool gives a source.
1777
1849
  try {
1778
1850
  return construct(domain, context);
1779
1851
  } catch (error) {
@@ -1801,8 +1873,8 @@ const compileExcept = (
1801
1873
  expression: Expression & { kind: "Except" },
1802
1874
  environment: Environment,
1803
1875
  ): Evaluator => {
1804
- const isKeptLazyExpression = keptLazyExpressions.has(expression);
1805
- if (isKeptLazyExpression) keepLazy(expression.function);
1876
+ const isKeptLazy = keptLazyExpressions.has(expression);
1877
+ if (isKeptLazy) keepLazy(expression.function);
1806
1878
  const evaluateFunction = getEvaluator(expression.function, environment);
1807
1879
  const updates = expression.updates.map((update) => ({
1808
1880
  path: update.path.map((step): CompiledStep =>
@@ -1835,18 +1907,19 @@ const compileExcept = (
1835
1907
  current,
1836
1908
  getKey(path[depth], context),
1837
1909
  (previous) => update(previous, path, depth + 1, context, value),
1838
- isKeptLazyExpression && depth === 0,
1910
+ isKeptLazy && depth === 0,
1839
1911
  );
1840
1912
  };
1841
1913
  return (context) => {
1842
1914
  let current = evaluateFunction(context);
1843
1915
  for (const item of updates) {
1844
- let isFound = false;
1916
+ // TLC leaves the value as it is when an update's path is not in it, and warns.
1917
+ const found = { value: false };
1845
1918
  current = update(current, item.path, 0, context, (inner) => {
1846
- isFound = true;
1919
+ found.value = true;
1847
1920
  return item.value(inner);
1848
1921
  });
1849
- if (!isFound) {
1922
+ if (!found.value) {
1850
1923
  context.environment.runtime.warn(
1851
1924
  MESSAGE_CODE.exceptAppliedToUnknownField,
1852
1925
  `The EXCEPT was applied to non-existing fields of the value at\n${describeRange(expression.function)}`,
@@ -1857,6 +1930,7 @@ const compileExcept = (
1857
1930
  };
1858
1931
  };
1859
1932
 
1933
+ // TLC filters any value it can't enumerate lazily, and fails only when it uses the result.
1860
1934
  export const getLazyFilter = (
1861
1935
  expression: Expression & { kind: "SetFilter" },
1862
1936
  environment: Environment,
@@ -1870,6 +1944,8 @@ export const getLazyFilter = (
1870
1944
  };
1871
1945
  const predicateNode = describeNode(expression.predicate);
1872
1946
  const coverage = environment.coverage;
1947
+ // TLC evaluates a lazy set's predicate under the set's node only as it enumerates the set,
1948
+ // and costs each element it tests and each it keeps.
1873
1949
  const testCovered = (node: number, isMember: boolean, test: () => Value) => {
1874
1950
  if (!coverage || node === -1) return test();
1875
1951
  if (!isMember) coverage.secondary[node]++;
@@ -2005,7 +2081,7 @@ const compileSetComprehension = (
2005
2081
  set,
2006
2082
  context.environment.runtime.version,
2007
2083
  );
2008
- let chosen: Value | undefined;
2084
+ const chosen = { value: undefined as Value | undefined };
2009
2085
  const pattern = expression.pattern;
2010
2086
  someElement(elements, (element) => {
2011
2087
  if (
@@ -2018,11 +2094,11 @@ const compileSetComprehension = (
2018
2094
  }
2019
2095
  const scope = bindPattern(context.scope, pattern, element);
2020
2096
  if (!expectBooleanBody(body(withScope(context, scope)), expression)) return false;
2021
- chosen = getBoundValue(pattern, scope);
2097
+ chosen.value = getBoundValue(pattern, scope);
2022
2098
  return true;
2023
2099
  });
2024
- if (chosen === undefined) throw createNoChoiceError(expression);
2025
- return chosen;
2100
+ if (chosen.value === undefined) throw createNoChoiceError(expression);
2101
+ return chosen.value;
2026
2102
  };
2027
2103
  };
2028
2104
 
@@ -35,6 +35,7 @@ const ACCESS_PUBLIC = 0x0001;
35
35
  const ACCESS_STATIC = 0x0008;
36
36
  const VALUE_PACKAGE = "tlc2/value/impl/";
37
37
 
38
+ // The constant pool tags of the JVM specification, section 4.4.
38
39
  const POOL_TAG = {
39
40
  utf8: 1,
40
41
  integer: 3,
@@ -67,10 +68,10 @@ const OPCODE = {
67
68
 
68
69
  const createReader = (bytes: Uint8Array) => {
69
70
  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
70
- let offset = 0;
71
+ const cursor = { offset: 0 };
71
72
  const advance = (length: number) => {
72
- const start = offset;
73
- offset += length;
73
+ const start = cursor.offset;
74
+ cursor.offset += length;
74
75
  return start;
75
76
  };
76
77
  return {
@@ -78,7 +79,7 @@ const createReader = (bytes: Uint8Array) => {
78
79
  readUint16: () => view.getUint16(advance(2)),
79
80
  readUint32: () => view.getUint32(advance(4)),
80
81
  readInt32: () => view.getInt32(advance(4)),
81
- readBytes: (length: number) => bytes.subarray(advance(length), offset),
82
+ readBytes: (length: number) => bytes.subarray(advance(length), cursor.offset),
82
83
  };
83
84
  };
84
85
 
@@ -94,6 +95,7 @@ const PRIMITIVE_TYPES = new Map([
94
95
  ["V", "void"],
95
96
  ]);
96
97
 
98
+ // The modifiers Method#toString prints, in the order of Modifier#toString.
97
99
  const METHOD_MODIFIERS: [number, string][] = [
98
100
  [0x0001, "public"],
99
101
  [0x0004, "protected"],
@@ -117,6 +119,8 @@ const getClassName = (pool: PoolEntry[], index: number) => pool[pool[index].firs
117
119
  const getJavaClassName = (pool: PoolEntry[], index: number) =>
118
120
  getClassName(pool, index).replaceAll("/", ".");
119
121
 
122
+ // In the order of the class file. Class#getDeclaredMethods orders them by where HotSpot allocated
123
+ // the symbols of their names.
120
124
  const readClassFile = (bytes: Uint8Array) => {
121
125
  const reader = createReader(bytes);
122
126
  if (reader.readUint32() !== CLASS_MAGIC)
@@ -177,6 +181,7 @@ const readClassFile = (bytes: Uint8Array) => {
177
181
  const isOverride = (access & ACCESS_PUBLIC) !== 0 && (access & ACCESS_STATIC) !== 0;
178
182
  if (!isOverride) continue;
179
183
  const code = attributes.find((attribute) => attribute.name === "Code")?.reader;
184
+ // A Code attribute holds max_stack and max_locals before the length of the bytecode.
180
185
  code?.readBytes(4);
181
186
  const thrown = attributes.find((attribute) => attribute.name === "Exceptions")?.reader;
182
187
  const exceptions = thrown
@@ -78,7 +78,8 @@ const NON_EXECUTE_PREFIX = ")]}'\n";
78
78
  const MALFORMED_JSON_GUIDE =
79
79
  "\nSee https://github.com/google/gson/blob/main/Troubleshooting.md#malformed-json";
80
80
 
81
- // Gson's JsonParser.parseReader: a lenient JsonReader reads one element, then, strict again, rejects anything but whitespace after it.
81
+ // Gson's JsonParser.parseReader: a lenient JsonReader reads one element, and the reader, strict
82
+ // again, then rejects anything but whitespace after it. An empty document reads as JSON null.
82
83
  export const readJson = (text: string): JsonElement => {
83
84
  const byteOrderMarkLength = text.startsWith("") ? 1 : 0;
84
85
  let pos = byteOrderMarkLength;
package/src/json.ts CHANGED
@@ -98,9 +98,12 @@ const toJson = (value: Value): string => {
98
98
  if (typeof value === "string") return toJsonString(value);
99
99
  if (typeof value !== "object") return String(value);
100
100
  if (value.kind === "ModelValue") return toJsonString(value.name);
101
- return getJavaClassName(value) === "RecordValue"
102
- ? toObjectJson(toFiniteFunction(value))
103
- : toJsonArray(value);
101
+ const className = getJavaClassName(value);
102
+ if (className === "RecordValue") return toObjectJson(toFiniteFunction(value));
103
+ if (className === "TupleValue") return toArrayJson(toFiniteFunction(value).range);
104
+ if (isFunctionClass(className)) return toFunctionJson(value);
105
+ if (isTlcEnumerable(value)) return toArrayJson(toFiniteSet(value).elements);
106
+ throw createUnsupportedError(value);
104
107
  };
105
108
 
106
109
  const toJsonArray = (value: Value) => {
@@ -171,7 +174,8 @@ const checkCharset = (charset: string) => {
171
174
  );
172
175
  };
173
176
 
174
- // Files.newBufferedWriter writes the text over the start of a file that it neither truncates nor appends to.
177
+ // Files.newBufferedWriter with the given StandardOpenOption names, which writes the text over the
178
+ // start of a file that it neither truncates nor appends to.
175
179
  const writeWithOptions = (files: FileSystem, path: string, names: string[], text: string) => {
176
180
  const unknown = names.find((name) => !OPEN_OPTIONS.has(name));
177
181
  if (unknown !== undefined) {
@@ -208,6 +212,7 @@ const writeWithOptions = (files: FileSystem, path: string, names: string[], text
208
212
  );
209
213
  };
210
214
 
215
+ // Java's File#getParentFile has no parent for a file name without a directory.
211
216
  const makeParentDirectory = (files: FileSystem, path: string) => {
212
217
  const separator = path.lastIndexOf("/");
213
218
  if (separator !== -1) files.makeDirectory?.(path.slice(0, Math.max(separator, 1)));
@@ -284,6 +289,8 @@ export const createJsonOperators = (files: FileSystem): Builtin[] => [
284
289
  ),
285
290
  ];
286
291
 
292
+ // TLC's Json overrides IOUtils!Serialize, as the CommunityModules define it, for the NDJSON format
293
+ // and falls back to its definition for any other.
287
294
  export const createIoUtilsOperators = (
288
295
  files: FileSystem,
289
296
  evaluateReplaced: (name: string, args: BuiltinArgument[], context: Context | undefined) => Value,