tla-ts 0.0.3-dev.fb38eba → 0.0.3-dev.fca2ca8

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.
@@ -12,12 +12,13 @@ import {
12
12
  import { BUNDLED_MODULES } from "./bundled-modules";
13
13
  import type { ConfigValue, ModelConfig } from "./config";
14
14
  import type { FileSystem } from "./json";
15
- import { TlaConfigError, TlaEvaluationError, TlaSyntaxError } from "./errors";
15
+ import { TlaConfigError, TlaEvaluationError, TlaModuleError, TlaSyntaxError } from "./errors";
16
16
  import { EXIT_STATUS, setExitCode } from "./exit-codes";
17
17
  import {
18
18
  createBigNumberError,
19
19
  createRealNumberError,
20
- isConstantLevel,
20
+ evaluate,
21
+ getDefinition,
21
22
  isTlcInteger,
22
23
  type Builtin,
23
24
  type Environment,
@@ -44,8 +45,9 @@ import {
44
45
  import { createRuntime } from "./runtime";
45
46
  import { CORE_OPERATORS, getStandardModule, STANDARD_DEPENDENCIES } from "./standard-modules";
46
47
  import { resolveInstanceSubexpressions, resolveModuleSubexpressions } from "./subexpressions";
47
- import { checkModuleLevels } from "./levels";
48
+ import { checkModuleLevels, createLevelAnalyzer } from "./levels";
48
49
  import { checkInstances, type InstanceCheck } from "./substitution-levels";
50
+ import { getTlcDeclarationOrder } from "./tlc-order";
49
51
  import {
50
52
  checkInteger,
51
53
  createModelValue,
@@ -212,6 +214,8 @@ export const createEnvironment = (
212
214
  const root = parseModule(options.source);
213
215
  const definitions = new Map<string, Definition>();
214
216
  const parameterized = new Map<string, boolean>();
217
+ // The definition each instance copy came from, and the instance parameters the copy adds.
218
+ const copySources = new Map<string, { source: string; prefix: number }>();
215
219
  const builtins = new Map<string, Builtin>(
216
220
  CORE_OPERATORS.map((operator) => [operator.name, operator]),
217
221
  );
@@ -379,10 +383,11 @@ export const createEnvironment = (
379
383
  variables: new Set(linked.variables),
380
384
  getDefinition: (key) => definitions.get(key),
381
385
  isParameterized: (key) => parameterized.get(key) === true,
382
- addDefinition: (name, create) => {
386
+ addDefinition: (source, name, create) => {
383
387
  const key = createName(`${name}@${module.name}`);
384
388
  definitions.set(key, create(key));
385
389
  parameterized.set(key, !isParameterFree);
390
+ copySources.set(key, { source, prefix: instance.params.length });
386
391
  return key;
387
392
  },
388
393
  createName,
@@ -544,7 +549,7 @@ export const createEnvironment = (
544
549
  variables: new Set(linked.variables),
545
550
  getDefinition: (key) => definitions.get(key),
546
551
  isParameterized: (key) => parameterized.get(key) === true,
547
- addDefinition: (name, create) => {
552
+ addDefinition: (_source, name, create) => {
548
553
  const key = `${name}${KEY_SEPARATOR}${instance.module}${suffix}.${copies.length}`;
549
554
  const definition = create(key);
550
555
  copies.push(
@@ -872,11 +877,51 @@ export const createEnvironment = (
872
877
  );
873
878
  }
874
879
  });
875
- declaredConstants.forEach((name) => {
876
- if (!constants.has(name) && !substitutions.has(name) && !operatorKeys.has(name)) {
877
- throw new TlaConfigError(`The constant ${name} is not assigned a value by the configuration`);
878
- }
880
+ // TLC sets a module-scoped entry on the body of the module's definition, which every instance of
881
+ // the module shares.
882
+ const scopedKeys = new Set(
883
+ [...config.constants, ...config.substitutions]
884
+ .filter((item) => item.module !== undefined)
885
+ .flatMap(getScopedKeys),
886
+ );
887
+ const getOverride = (
888
+ key: string,
889
+ prefix: number,
890
+ ): { key: string; prefix: number } | undefined => {
891
+ if (scopedKeys.has(key)) return { key, prefix };
892
+ const copy = copySources.get(key);
893
+ return copy && getOverride(copy.source, prefix + copy.prefix);
894
+ };
895
+ copySources.forEach((copy, key) => {
896
+ const override = getOverride(copy.source, copy.prefix);
897
+ const definition = definitions.get(key);
898
+ if (!override || !definition) return;
899
+ const params = definition.kind === "Operator" ? definition.params : [];
900
+ const alias = createLocalAlias(
901
+ key,
902
+ override.key,
903
+ params,
904
+ params.slice(override.prefix),
905
+ definition.location,
906
+ );
907
+ definitions.set(key, alias);
908
+ linkedRoot.visible.forEach((symbol, name) => {
909
+ if (symbol.key === key && name !== key) definitions.set(name, alias);
910
+ });
879
911
  });
912
+ const unassigned = declaredConstants.filter(
913
+ (name) => !constants.has(name) && !substitutions.has(name) && !operatorKeys.has(name),
914
+ );
915
+ if (unassigned.length > 0) {
916
+ // TLC reports the first constant it finds unassigned in SANY's order of declarations.
917
+ const name =
918
+ getTlcDeclarationOrder(options.source, options.loadModule, "constant").find((constant) =>
919
+ unassigned.includes(constant),
920
+ ) ?? unassigned[0];
921
+ throw new TlaConfigError(
922
+ `The constant parameter ${name} is not assigned a value by the configuration file.`,
923
+ );
924
+ }
880
925
 
881
926
  const environment: Environment = {
882
927
  runtime,
@@ -907,18 +952,43 @@ export const createEnvironment = (
907
952
  getDefinition: (symbol) => definitions.get(linked.visible.get(symbol)?.key ?? symbol),
908
953
  };
909
954
  });
955
+ // TLC evaluates a substitute at startup and rejects it only when that fails and the level bound it
956
+ // computes is above constant. The bound counts the operators that TLC's Java code overrides with
957
+ // a minimum level as state-level, so the analyzer takes them for variables.
958
+ const analyzer = createLevelAnalyzer({
959
+ constants: new Set(constants.keys()),
960
+ variables: new Set([
961
+ ...variables,
962
+ ...["TLCGet", "Trace", "CounterExample"].filter((name) => builtins.has(name)),
963
+ ]),
964
+ getDefinition: (name) => getDefinition(name, environment),
965
+ });
966
+ const getEvaluationError = (body: Expression) => {
967
+ try {
968
+ evaluate(body, { environment, scope: undefined, state: undefined, next: undefined });
969
+ return undefined;
970
+ } catch (error) {
971
+ if (error instanceof TlaEvaluationError) return error;
972
+ throw error;
973
+ }
974
+ };
910
975
  substitutions.forEach((target, name) => {
911
976
  const definition = definitions.get(target);
912
- if (
977
+ const error =
913
978
  declaredConstants.includes(name) &&
914
- definition &&
915
- !isConstantLevel(definition, environment)
916
- ) {
979
+ definition?.kind === "Operator" &&
980
+ definition.params.length === 0 &&
981
+ analyzer.analyzeDefinition(definition, new Map()).level > 0
982
+ ? getEvaluationError(definition.body)
983
+ : undefined;
984
+ // TLC adds the reason unless a standard module's Java code failed.
985
+ if (error) {
917
986
  throw new TlaConfigError(
918
- `The configuration file substitutes constant ${name} with non-constant ${target}`,
987
+ `The configuration file substitutes constant ${name} with non-constant ${target}${error instanceof TlaModuleError ? "" : ` - specifically: ${error.message}`}`,
919
988
  );
920
989
  }
921
990
  });
991
+ runtime.isStarted = true;
922
992
  return {
923
993
  environment,
924
994
  assumptions,
package/src/errors.ts CHANGED
@@ -1,10 +1,18 @@
1
1
  import { EXIT_STATUS, getExitCode } from "./exit-codes";
2
+ import type { Value } from "./values";
2
3
 
3
4
  // How TLC reports a RuntimeException it did not expect, such as one raised while computing next
4
5
  // states.
5
6
  export const UNEXPECTED_EXCEPTION =
6
7
  "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: ";
7
8
 
9
+ // How TLC reports a Java StackOverflowError, which V8 raises as this RangeError.
10
+ export const STACK_OVERFLOW =
11
+ "This was a Java StackOverflowError. It was probably the result\nof an incorrect recursive function definition that caused TLC to enter\nan infinite loop when trying to compute the function or its application\nto an element in its putative domain.";
12
+
13
+ export const isStackOverflow = (error: unknown) =>
14
+ error instanceof RangeError && error.message === "Maximum call stack size exceeded";
15
+
8
16
  export class TlaError extends Error {
9
17
  constructor(message: string, cause?: unknown) {
10
18
  super(message, { cause });
@@ -55,6 +63,24 @@ export class TlaModuleError extends TlaEvaluationError {
55
63
  }
56
64
  }
57
65
 
66
+ // TLC reports a successor state that the next-state relation leaves incomplete as an error of its
67
+ // own, not as an exception. It keeps the name TlaEvaluationError, and index.ts doesn't export it.
68
+ export class TlaIncompleteStateError extends TlaEvaluationError {
69
+ state: (Value | undefined)[];
70
+ action: string | undefined;
71
+ missing: string[];
72
+
73
+ constructor(state: (Value | undefined)[], action: string | undefined, missing: string[]) {
74
+ super(
75
+ `Successor state is not completely specified by the next-state action. The following variable${missing.length > 1 ? "s are" : " is"} not defined: ${missing.join(", ")}.\n`,
76
+ );
77
+ this.name = "TlaEvaluationError";
78
+ this.state = state;
79
+ this.action = action;
80
+ this.missing = missing;
81
+ }
82
+ }
83
+
58
84
  export interface TlapmReport {
59
85
  failure?: string;
60
86
  exception?: string;
package/src/evaluate.ts CHANGED
@@ -14,7 +14,7 @@ import {
14
14
  } from "./ast";
15
15
  import { getKindString } from "./builtins";
16
16
  import { TlaEvaluationError } from "./errors";
17
- import { EXIT_STATUS, setExitCode } from "./exit-codes";
17
+ import { EXIT_STATUS, setExitCode, setOwnExitCode } from "./exit-codes";
18
18
  import { generateEvaluator } from "./codegen";
19
19
  import type { CheckerRuntime } from "./runtime";
20
20
  import { getReadVariables } from "./dependencies";
@@ -30,23 +30,26 @@ import {
30
30
  createSortedSet,
31
31
  createWrittenRecord,
32
32
  createTuple,
33
+ describeMissingField,
33
34
  formatValue,
34
35
  getDomain,
35
36
  getFunctionDomain,
36
37
  getIntervalElements,
37
38
  getSequenceElements,
38
39
  getValueHash,
39
- isEnumerable,
40
40
  isFunctionValue,
41
41
  isOverriddenSet,
42
+ isRecordValue,
42
43
  isSameValue,
43
44
  markLambdaFunction,
45
+ isReducible,
44
46
  isSetValue,
45
47
  MAXIMUM_INTEGER,
46
48
  MINIMUM_INTEGER,
47
49
  toFiniteSet,
48
50
  updateFunction,
49
51
  valuesEqual,
52
+ type FunctionValue,
50
53
  type LazyFunctionSource,
51
54
  type LazyFunctionValue,
52
55
  type Value,
@@ -182,8 +185,17 @@ export const getConjunctError = (
182
185
  };
183
186
 
184
187
  export const getFieldError =
185
- (expression: Expression & { kind: "FieldAccess" }) => (record: Value) =>
186
- `Attempted to select nonexistent field "${expression.field}" from the record\n${formatValue(record)}\n${describeRange(expression)}`;
188
+ (expression: Expression & { kind: "FieldAccess" }) => (record: FunctionValue) =>
189
+ isRecordValue(record)
190
+ ? `Attempted to select nonexistent field "${expression.field}" from the record\n${formatValue(record)}\n${describeRange(expression)}`
191
+ : describeMissingField(record, expression.field);
192
+
193
+ export const getNonFunctionError = (expression: Expression) => (value: Value) =>
194
+ `A non-function (${getKindString(value)}) was applied as a function.\n${describeRange(expression)}`;
195
+
196
+ export const getNonRecordError =
197
+ (expression: Expression & { kind: "FieldAccess" }) => (value: Value) =>
198
+ `Attempted to select field "${expression.field}" from a non-record value ${formatValue(value)}\n${describeRange(expression)}`;
187
199
 
188
200
  export const getDomainOperator = (expression: Expression) => (value: Value) => {
189
201
  if (!isFunctionValue(value)) {
@@ -1027,7 +1039,7 @@ export const getEvaluator = (expression: Expression, environment: Environment):
1027
1039
 
1028
1040
  const entryEvaluators = new WeakMap<Expression, Evaluator>();
1029
1041
 
1030
- const getEntryEvaluator = (expression: Expression, environment: Environment) => {
1042
+ export const getEntryEvaluator = (expression: Expression, environment: Environment) => {
1031
1043
  const cached = entryEvaluators.get(expression);
1032
1044
  if (cached) return cached;
1033
1045
  const evaluator =
@@ -1325,6 +1337,11 @@ const compileApply = (
1325
1337
  if (definition?.kind === "Function") {
1326
1338
  throw new TlaEvaluationError(`${expression.operator} is a function; apply it with brackets`);
1327
1339
  }
1340
+ if (expression.operator === "\\cdot") {
1341
+ throw new TlaEvaluationError(
1342
+ "The current version of TLC does not support action composition. An incomplete implementation can be enabled via the tlc2.tool.impl.Tool.cdot=true java property.",
1343
+ );
1344
+ }
1328
1345
  throw new TlaEvaluationError(
1329
1346
  `Unknown operator ${expression.operator} at ${describeLocation(expression)}`,
1330
1347
  );
@@ -1420,7 +1437,13 @@ const compileFunctionConstruction = (
1420
1437
  const set = getEvaluator(bound.set, environment);
1421
1438
  return (context) => {
1422
1439
  const domain = isSingleName ? set(context) : getBoundsDomain(bounds, context);
1423
- if (expression.isRecursive || isKeptLazy || !isEnumerable(domain)) {
1440
+ // TLC builds the function only when it reduces every domain, and evaluates the body lazily
1441
+ // otherwise.
1442
+ const domains =
1443
+ typeof domain === "object" && domain.kind === "ProductSet" && bounds.length > 1
1444
+ ? domain.factors
1445
+ : [domain];
1446
+ if (expression.isRecursive || isKeptLazy || !domains.every(isReducible)) {
1424
1447
  const functionValue = createLazyFunction(
1425
1448
  domain,
1426
1449
  (argument) => body(withScope(context, bindArgument(bounds, context.scope, argument))),
@@ -1514,10 +1537,7 @@ const compileSetComprehension = (
1514
1537
  predicate(withScope(context, bindPattern(context.scope, pattern, element))),
1515
1538
  "a set filter predicate",
1516
1539
  );
1517
- const isReducible =
1518
- typeof base === "object" &&
1519
- (base.kind === "Set" || base.kind === "MixedSet" || base.kind === "Interval");
1520
- if (!isReducible) {
1540
+ if (!isReducible(base)) {
1521
1541
  if (isSetValue(base)) return { kind: "FilteredSet", base, test };
1522
1542
  throw new TlaEvaluationError(
1523
1543
  `TLC encountered a non-enumerable quantifier bound ${formatValue(base)} at ${describeLocation(expression.bound.set)}`,
@@ -1571,7 +1591,12 @@ export const hasDuplicateFields = (sortedFields: RecordField[]) =>
1571
1591
  sortedFields.some((field, index) => index > 0 && sortedFields[index - 1].name === field.name);
1572
1592
 
1573
1593
  export const createUnassignedError = (name: string, expression: Expression) =>
1574
- new TlaEvaluationError(`The variable ${name} is not assigned at ${describeLocation(expression)}`);
1594
+ setOwnExitCode(
1595
+ new TlaEvaluationError(
1596
+ `In evaluation, the identifier ${name} is either undefined or not an operator.\n${describeRange(expression)}`,
1597
+ ),
1598
+ EXIT_STATUS.configParseError,
1599
+ );
1575
1600
 
1576
1601
  export const createPrimeOutsideActionError = (expression: Expression) =>
1577
1602
  new TlaEvaluationError(
@@ -1759,18 +1784,31 @@ const compile = (expression: Expression, environment: Environment): Evaluator =>
1759
1784
  keepLazy(expression.function);
1760
1785
  const evaluateFunction = child(expression.function);
1761
1786
  const args = expression.args.map(child);
1787
+ const describeNonFunction = getNonFunctionError(expression);
1762
1788
  if (args.length === 1) {
1763
1789
  const argument = args[0];
1764
- return (context) => applyFunction(evaluateFunction(context), argument(context));
1790
+ return (context) =>
1791
+ applyFunction(
1792
+ evaluateFunction(context),
1793
+ argument(context),
1794
+ undefined,
1795
+ describeNonFunction,
1796
+ );
1765
1797
  }
1766
1798
  return (context) =>
1767
- applyFunction(evaluateFunction(context), createTuple(args.map((arg) => arg(context))));
1799
+ applyFunction(
1800
+ evaluateFunction(context),
1801
+ createTuple(args.map((arg) => arg(context))),
1802
+ undefined,
1803
+ describeNonFunction,
1804
+ );
1768
1805
  }
1769
1806
  case "FieldAccess": {
1770
1807
  const record = child(expression.record);
1771
1808
  const field = expression.field;
1772
1809
  const describeMissing = getFieldError(expression);
1773
- return (context) => applyFunction(record(context), field, describeMissing);
1810
+ const describeNonRecord = getNonRecordError(expression);
1811
+ return (context) => applyFunction(record(context), field, describeMissing, describeNonRecord);
1774
1812
  }
1775
1813
  case "Product": {
1776
1814
  const factors = expression.factors.map(child);
package/src/exit-codes.ts CHANGED
@@ -26,7 +26,19 @@ export const setExitCode = <Thrown>(error: Thrown, code: number) => {
26
26
 
27
27
  export const getExitCode = (error: Error) => exitCodes.get(error);
28
28
 
29
- // TLC exits with 255 when it fails to process or evaluate a liveness property, in any phase.
29
+ const ownExitCodes = new WeakMap<Error, number>();
30
+
31
+ // The exit status of the error code TLC gives an EvalException, which TLC uses only where it
32
+ // doesn't report the error again as a nested expression.
33
+ export const setOwnExitCode = <Thrown extends Error>(error: Thrown, code: number) => {
34
+ ownExitCodes.set(error, code);
35
+ return error;
36
+ };
37
+
38
+ export const getOwnExitCode = (error: unknown) =>
39
+ error instanceof Error ? ownExitCodes.get(error) : undefined;
40
+
41
+ // TLC exits with 255 when it fails to process or evaluate a liveness property.
30
42
  const withErrorExitCode = <Result>(run: () => Result) => {
31
43
  try {
32
44
  return run();
@@ -41,8 +53,15 @@ export const withLivenessExitCode = (
41
53
  const checker = withErrorExitCode(create);
42
54
  return (
43
55
  checker && {
44
- addInitialState: (index, state) =>
45
- withErrorExitCode(() => checker.addInitialState(index, state)),
56
+ // TLC replays the initial states to report an error, but skips the liveness check of a
57
+ // state it has already seen, so it exits with the status of the error's own code.
58
+ addInitialState: (index, state) => {
59
+ try {
60
+ checker.addInitialState(index, state);
61
+ } catch (error) {
62
+ throw setExitCode(error, getOwnExitCode(error) ?? EXIT_STATUS.error);
63
+ }
64
+ },
46
65
  addState: (index, state, successors) =>
47
66
  withErrorExitCode(() => checker.addState(index, state, successors)),
48
67
  findViolation: () => withErrorExitCode(() => checker.findViolation()),
package/src/instances.ts CHANGED
@@ -219,7 +219,7 @@ interface Instantiation {
219
219
  variables: Set<string>;
220
220
  getDefinition: (key: string) => Definition | undefined;
221
221
  isParameterized: (key: string) => boolean;
222
- addDefinition: (name: string, create: (key: string) => Definition) => string;
222
+ addDefinition: (source: string, name: string, create: (key: string) => Definition) => string;
223
223
  createName: (name: string) => string;
224
224
  }
225
225
 
@@ -640,7 +640,7 @@ const copyDefinition = (rewrite: Rewrite, key: string): string => {
640
640
  const instantiation = rewrite.instantiation;
641
641
  const definition = instantiation.getDefinition(key);
642
642
  if (!definition) return key;
643
- return instantiation.addDefinition(definition.name, (copyKey) => {
643
+ return instantiation.addDefinition(key, definition.name, (copyKey) => {
644
644
  rewrite.copies.set(key, copyKey);
645
645
  const rename = createRenamer(rewrite);
646
646
  const mapped = renameParams(
@@ -679,7 +679,7 @@ export const createInstantiation = (instantiation: Instantiation) => {
679
679
  if (copy !== undefined) return copy;
680
680
  const definition = instantiation.getDefinition(key);
681
681
  if (!definition) return key;
682
- return instantiation.addDefinition(definition.name, () =>
682
+ return instantiation.addDefinition(key, definition.name, () =>
683
683
  withInstanceParams(definition, instantiation.params, definition.location),
684
684
  );
685
685
  },