tla-ts 0.0.1 → 0.0.3-dev.3cf2ad0

package/src/environment.ts

@@ -12,18 +12,40 @@ import { BUNDLED_MODULES } from "./bundled-modules";
 import type { ConfigValue, ModelConfig } from "./config";
 import type { FileSystem } from "./json";
 import { TlaConfigError, TlaEvaluationError, TlaSyntaxError } from "./errors";
-import { getChildren, isConstantLevel, type Builtin, type Environment } from "./evaluate";
+import { EXIT_STATUS, setExitCode } from "./exit-codes";
+import {
+  createBigNumberError,
+  createRealNumberError,
+  getChildren,
+  isConstantLevel,
+  isTlcInteger,
+  type Builtin,
+  type Environment,
+} from "./evaluate";
 import {
   createInstantiation,
   getEnabledVariableName,
   renameLocals,
   withLetInstances,
 } from "./instances";
-import { parseModule } from "./parser";
-import { KEY_SEPARATOR, resolveModule, resolveSubstitutions, type Symbols } from "./resolve";
+import { overrideDefinitions } from "./java-overrides";
+import { extractModule, parseModule } from "./parser";
+import {
+  checkRedefinitions,
+  getArity,
+  isBefore,
+  KEY_SEPARATOR,
+  LOCAL_RESOLUTION,
+  resolveModule,
+  resolveSubstitutions,
+  type ModuleSymbol,
+  type Symbols,
+} from "./resolve";
 import { createRuntime } from "./runtime";
-import { CORE_OPERATORS, getStandardModule } from "./standard-modules";
+import { CORE_OPERATORS, getStandardModule, STANDARD_DEPENDENCIES } from "./standard-modules";
 import { resolveInstanceSubexpressions, resolveModuleSubexpressions } from "./subexpressions";
+import { checkModuleLevels } from "./levels";
+import { checkInstances, type InstanceCheck } from "./substitution-levels";
 import {
   checkInteger,
   createModelValue,
@@ -33,21 +55,36 @@ import {
   type Value,
 } from "./values";
 
-export interface EnvironmentOptions {
+interface EnvironmentOptions {
+  source: string;
   loadModule: ((name: string) => string | undefined) | undefined;
+  loadClass?: (name: string) => Uint8Array | undefined;
   print: (text: string) => void;
   files: FileSystem;
+  seed?: bigint;
 }
 
-export interface Specification {
+interface Specification {
   environment: Environment;
   assumptions: Assumption[];
+  variableLocations: SourceLocation[];
+  instanceActions: Map<string, InstanceAction>;
+}
+
+export interface InstanceAction {
+  name: string;
+  location: SourceLocation;
 }
 
 const toValue = (value: ConfigValue): Value => {
   switch (value.kind) {
     case "Number":
-      return checkInteger(value.value);
+      try {
+        return checkInteger(value.value);
+      } catch (error) {
+        // TLC fails with an unexpected exception on a configuration number too big for it.
+        throw setExitCode(error, EXIT_STATUS.error);
+      }
     case "String":
     case "Boolean":
       return value.value;
@@ -62,11 +99,29 @@ interface LinkedModule {
   module: Module;
   constants: Declaration[];
   variables: string[];
+  variableLocations: SourceLocation[];
   visible: Symbols;
   exported: Symbols;
+  modules: Map<string, LinkedModule>;
+  extended: LinkedModule[];
+}
+
+interface ModuleScope {
+  id: string;
+  symbols: Symbols;
+  modules: Map<string, LinkedModule>;
+  nested: Module[];
 }
 
-const LOCAL_RESOLUTION = { kind: "Local" } as const;
+const getDeclarations = (linked: LinkedModule) => [
+  ...linked.constants,
+  ...linked.variables.map((variable) => ({ name: variable, arity: 0 })),
+];
+
+const createModuleRedefinedError = (module: Module) =>
+  new TlaSyntaxError(
+    `Multiply-defined module '${module.name}' at line ${module.location.line}, column ${module.location.column}`,
+  );
 
 const createLocalFunction = (definition: Definition, key: string): Definition => ({
   kind: "Operator",
@@ -88,37 +143,42 @@ const createLocalFunction = (definition: Definition, key: string): Definition =>
   location: definition.location,
 });
 
-const createOperatorConstant = (name: string, rows: [Value[], Value][]): Builtin => ({
-  kind: "Builtin",
-  name,
-  arity: rows[0][0].length,
-  evaluate: (args) => {
-    const row = rows.find((candidate) =>
-      candidate[0].every((value, index) => {
-        const argument = args[index];
-        return (
-          !(typeof argument === "object" && argument.kind === "Operator") &&
-          valuesEqual(value, argument)
-        );
-      }),
-    );
-    if (row) return row[1];
-    throw new TlaEvaluationError(
-      `Attempted to apply operator:\n${name}\nto arguments (${args.map((argument) => (typeof argument === "object" && argument.kind === "Operator" ? argument.name : formatValue(argument))).join(", ")}), which is undefined.`,
-    );
-  },
-  evaluateUnary: undefined,
-  evaluateBinary: undefined,
-});
+const createOperatorConstant = (name: string, arity: number, rows: [Value[], Value][]): Builtin => {
+  const table = `{ ${rows.map((row) => `<${[...row[0], row[1]].map((value) => formatValue(value)).join(", ")}>`).join(", ")}}`;
+  return {
+    kind: "Builtin",
+    name,
+    arity,
+    evaluate: (args) => {
+      const row = rows.find((candidate) => {
+        if (candidate[0].length !== args.length) {
+          throw new TlaEvaluationError(
+            `Attempted to apply the operator ${table}\nwith wrong number of arguments.`,
+          );
+        }
+        return candidate[0].every((value, index) => {
+          const argument = args[index];
+          return (
+            !(typeof argument === "object" && argument.kind === "Operator") &&
+            valuesEqual(value, argument)
+          );
+        });
+      });
+      if (row) return row[1];
+      throw new TlaEvaluationError(
+        `Attempted to apply operator:\n${table}\nto arguments (${args.map((argument) => (typeof argument === "object" && argument.kind === "Operator" ? argument.name : formatValue(argument))).join(", ")}), which is undefined.`,
+      );
+    },
+    evaluateUnary: undefined,
+    evaluateBinary: undefined,
+  };
+};
 
 const mentionsName = (expression: Expression, names: Set<string>): boolean =>
   (expression.kind === "Identifier" && names.has(expression.name)) ||
   (expression.kind === "Apply" && names.has(expression.operator)) ||
   getChildren(expression).some((child) => mentionsName(child, names));
 
-const getArity = (definition: Definition) =>
-  definition.kind === "Operator" ? definition.params.length : 0;
-
 const getVariableIndex = (variables: string[], declared: string[]) => {
   const index = new Map(variables.map((name, position) => [name, position]));
   new Set(declared).forEach((name) =>
@@ -127,20 +187,53 @@ const getVariableIndex = (variables: string[], declared: string[]) => {
   return index;
 };
 
+const getSubstitutions = (instances: Instance[]) =>
+  instances.flatMap((instance) =>
+    instance.substitutions.map((substitution) => substitution.expression),
+  );
+
+const rejectLiterals = (expressions: Expression[]): void =>
+  expressions.forEach((expression) => {
+    if (expression.kind === "Decimal") throw createRealNumberError(expression);
+    if (expression.kind === "Number" && !isTlcInteger(expression.value)) {
+      throw createBigNumberError(expression);
+    }
+    rejectLiterals(
+      expression.kind === "Let"
+        ? [...getChildren(expression), ...getSubstitutions(expression.instances ?? [])]
+        : getChildren(expression),
+    );
+  });
+
 export const createEnvironment = (
-  root: Module,
   config: ModelConfig,
   options: EnvironmentOptions,
 ): Specification => {
+  const root = parseModule(options.source);
   const definitions = new Map<string, Definition>();
   const parameterized = new Map<string, boolean>();
   const builtins = new Map<string, Builtin>(
     CORE_OPERATORS.map((operator) => [operator.name, operator]),
   );
   const standardExports = new Map<string, Symbols>();
-  const runtime = createRuntime(config.checkDeadlock);
+  const runtime = createRuntime(config.checkDeadlock, options.seed);
   const linkedModules = new Map<string, LinkedModule>();
+  const nestedModules = new Map<string, LinkedModule>();
+  const linkedList: LinkedModule[] = [];
+  const dependencies = new Map<string, Set<string>>();
+  const loading: Set<string>[] = [];
+  // The top-level modules being linked, to report a cycle of EXTENDS or INSTANCE.
+  const linking: string[] = [];
+
+  const useModule = (name: string, used: Iterable<string>) =>
+    loading.forEach((closure) => {
+      closure.add(name);
+      [...used].forEach((dependency) => closure.add(dependency));
+    });
   const copyCount = { value: 0 };
+  const createName = (name: string) => `${name}#${copyCount.value++}`;
+  const instanceChecks: InstanceCheck[] = [];
+  const instanceActions = new Map<string, InstanceAction>();
 
   const addStandardModule = (name: string): Symbols | undefined => {
     const cached = standardExports.get(name);
@@ -161,65 +254,108 @@ export const createEnvironment = (
     return exported;
   };
 
-  const nestedModules = new Map<string, Module>();
-  const outerModules = new Map<string, Module>();
-  const addNestedModules = (module: Module): Module => {
-    module.modules.forEach((nested) => {
-      if (nestedModules.has(nested.name)) return;
-      outerModules.set(nested.name, module);
-      nestedModules.set(nested.name, addNestedModules(nested));
-    });
+  const getStandardSymbols = (name: string) => {
+    const symbols = addStandardModule(name);
+    if (symbols) useModule(name, STANDARD_DEPENDENCIES.get(name) ?? []);
+    return symbols;
+  };
+
+  // Like TLC, reject a decimal or a big integer anywhere in a module, even where nothing evaluates it.
+  const rejectModuleLiterals = (module: Module): Module => {
+    rejectLiterals([
+      ...module.definitions.flatMap((definition) =>
+        definition.kind === "Function"
+          ? [...definition.bounds.map((bound) => bound.set), definition.body]
+          : [definition.body],
+      ),
+      ...module.assumptions.map((assumption) => assumption.expression),
+      ...module.theorems.flatMap((theorem) =>
+        theorem.statement.kind === "AssumeProve" ? [] : [theorem.statement],
+      ),
+      ...getSubstitutions(module.instances),
+    ]);
+    module.modules.forEach(rejectModuleLiterals);
     return module;
   };
-  addNestedModules(root);
+  rejectModuleLiterals(root);
 
-  const loadModule = (name: string) => {
-    const nested = nestedModules.get(name);
-    if (nested) return nested;
-    const source = options.loadModule?.(name) ?? BUNDLED_MODULES.get(name);
+  const loadModule = (name: string, importer: string) => {
+    const source =
+      options.loadModule?.(name) ??
+      BUNDLED_MODULES.get(name) ??
+      extractModule(options.source, name);
     if (source === undefined)
-      throw new TlaSyntaxError(`Cannot find source file for module ${name}`);
-    return addNestedModules(parseModule(source));
+      throw new TlaSyntaxError(
+        `Cannot find source file for module ${name} imported in module ${importer}.`,
+      );
+    const module = parseModule(source);
+    if (module.name !== name) {
+      throw new TlaSyntaxError(
+        `File name '${name}' does not match the name '${module.name}' of the top level module it contains.`,
+      );
+    }
+    return rejectModuleLiterals(module);
   };
 
-  const getDefinitionKey = (module: Module, name: string) =>
-    module === root ? name : `${name}${KEY_SEPARATOR}${module.name}`;
-
-  const getOuterKey = (module: Module, name: string): string => {
-    const outer = outerModules.get(module.name);
-    if (!outer || !module.outer) return name;
-    if (outer.definitions.some((definition) => definition.name === name)) {
-      return getDefinitionKey(outer, name);
+  const linkTopLevel = (parsed: Module) => {
+    const cycleStart = linking.indexOf(parsed.name);
+    if (cycleStart !== -1) {
+      const cycle = [...linking.slice(cycleStart), parsed.name].map((name) => `${name}.tla`);
+      throw new TlaSyntaxError(
+        `Circular dependency among .tla files; dependency cycle is: ${cycle.join(" --> ")}`,
+      );
     }
-    const isDeclared =
-      outer.constants.some((constant) => constant.name === name) || outer.variables.includes(name);
-    return isDeclared ? name : getOuterKey(outer, name);
+    const closure = new Set<string>();
+    const nested: Module[] = [];
+    linking.push(parsed.name);
+    loading.push(closure);
+    const linked = linkModule(parsed, {
+      id: parsed.name,
+      symbols: new Map(),
+      modules: new Map(),
+      nested,
+    });
+    loading.pop();
+    linking.pop();
+    const duplicate = nested.find((module) => closure.has(module.name));
+    if (duplicate) throw createModuleRedefinedError(duplicate);
+    return { linked, closure };
   };
 
-  const getLinkedModule = (name: string) => linkedModules.get(name) ?? linkModule(loadModule(name));
+  const getLinkedModule = (name: string, importer: string): LinkedModule => {
+    const cached = linkedModules.get(name);
+    if (cached) {
+      useModule(name, dependencies.get(name) ?? []);
+      return cached;
+    }
+    const top = linkTopLevel(loadModule(name, importer));
+    linkedModules.set(name, top.linked);
+    dependencies.set(name, top.closure);
+    useModule(name, top.closure);
+    return top.linked;
+  };
 
   const instantiate = (
     instance: Instance,
     module: Module,
     unit: {
       imported: Symbols;
+      importedAt: Map<string, SourceLocation>;
       definitions: Map<string, Definition>;
       getKey: (definition: Definition) => string;
     },
     isParameterFree: boolean,
+    nested: LinkedModule | undefined,
   ): Symbols => {
-    const standardSymbols = addStandardModule(instance.module);
+    const standardSymbols = nested ? undefined : getStandardSymbols(instance.module);
     if (standardSymbols) {
       if (instance.name === undefined) return standardSymbols;
       return new Map(
         [...standardSymbols].map(([name, symbol]) => [`${instance.name}!${name}`, symbol]),
       );
     }
-    const linked = getLinkedModule(instance.module);
-    const declarations = [
-      ...linked.constants,
-      ...linked.variables.map((variable) => ({ name: variable, arity: 0 })),
-    ];
+    const linked = nested ?? getLinkedModule(instance.module, module.name);
+    const declarations = getDeclarations(linked);
     const suffix = `#${copyCount.value++}`;
     const renamed = new Map(instance.params.map((param) => [param.name, `${param.name}${suffix}`]));
     const substitutions = resolveSubstitutions(
@@ -228,6 +364,13 @@ export const createEnvironment = (
       module,
       unit,
     );
+    instanceChecks.push({
+      module: instance.module,
+      instancer: module.name,
+      lets: [],
+      substitutions,
+      location: instance.location,
+    });
     const instantiation = createInstantiation({
       params: instance.params.map((param) => ({ ...param, name: `${param.name}${suffix}` })),
       substitutions: new Map(
@@ -237,22 +380,30 @@ export const createEnvironment = (
       getDefinition: (key) => definitions.get(key),
       isParameterized: (key) => parameterized.get(key) === true,
       addDefinition: (name, create) => {
-        const key = `${name}@${module.name}#${copyCount.value++}`;
+        const key = createName(`${name}@${module.name}`);
         definitions.set(key, create(key));
         parameterized.set(key, !isParameterFree);
         return key;
       },
+      createName,
     });
     const declared = new Set(declarations.map((declaration) => declaration.name));
     const symbols: Symbols = new Map();
     linked.exported.forEach((symbol, name) => {
       if (declared.has(name)) return;
       if (instance.name === undefined) {
-        symbols.set(name, { key: instantiation.getKey(symbol.key), arity: symbol.arity });
+        const key = instantiation.getKey(symbol.key);
+        if (declarations.length > 0)
+          instanceActions.set(key, { name, location: instance.location });
+        symbols.set(name, { key, arity: symbol.arity });
         return;
       }
+      const key = instantiation.getQualifiedKey(symbol.key);
+      if (declarations.length > 0) {
+        instanceActions.set(key, { name: `${instance.name}!${name}`, location: instance.location });
+      }
       symbols.set(`${instance.name}!${name}`, {
-        key: instantiation.getQualifiedKey(symbol.key),
+        key,
         arity: symbol.arity + instance.params.length,
       });
     });
@@ -291,7 +442,7 @@ export const createEnvironment = (
 
   const getSubstitutionBody = (
     replacement: Expression,
-    declaration: Declaration,
+    declaration: OperatorParam,
     location: SourceLocation,
   ): { params: OperatorParam[]; body: Expression } => {
     if (declaration.arity === 0) return { params: [], body: replacement };
@@ -314,10 +465,14 @@ export const createEnvironment = (
     };
   };
 
-  const instantiateLocally = (instance: Instance): Definition[] => {
+  const instantiateLocally = (
+    instance: Instance,
+    lets: Definition[],
+    instancer: string,
+    nested: LinkedModule | undefined,
+  ): Definition[] => {
     const location = instance.location;
-    const instanceParams = instance.params;
-    const standardSymbols = addStandardModule(instance.module);
+    const standardSymbols = nested ? undefined : getStandardSymbols(instance.module);
     if (standardSymbols) {
       if (instance.name === undefined) return [];
       return [...standardSymbols].map(([name, symbol]) => {
@@ -325,23 +480,29 @@ export const createEnvironment = (
         return createLocalAlias(
           `${instance.name}!${name}`,
           symbol.key,
-          [...instanceParams, ...forwarded],
+          [...instance.params, ...forwarded],
           forwarded,
           location,
         );
       });
     }
-    const linked = getLinkedModule(instance.module);
+    const linked = nested ?? getLinkedModule(instance.module, instancer);
     const suffix = `#${copyCount.value++}`;
     const explicit = new Map(instance.substitutions.map((item) => [item.name, item.expression]));
-    const declarations = [
-      ...linked.constants,
-      ...linked.variables.map((variable) => ({ name: variable, arity: 0 })),
-    ];
-    const getReplacement = (declaration: Declaration): Expression =>
+    const declarations = getDeclarations(linked);
+    const getReplacement = (declaration: OperatorParam): Expression =>
       explicit.get(declaration.name) ?? { kind: "Identifier", name: declaration.name, location };
-    const instanceNames = new Set(instanceParams.map((param) => param.name));
-    const isParameterDependent = (declaration: Declaration) =>
+    instanceChecks.push({
+      module: instance.module,
+      instancer,
+      lets,
+      substitutions: new Map(
+        declarations.map((declaration) => [declaration.name, getReplacement(declaration)]),
+      ),
+      location,
+    });
+    const instanceNames = new Set(instance.params.map((param) => param.name));
+    const isParameterDependent = (declaration: OperatorParam) =>
       mentionsName(getReplacement(declaration), instanceNames);
     const substitutionDefinitions = declarations.map((declaration): Definition => {
       const substitution = getSubstitutionBody(getReplacement(declaration), declaration, location);
@@ -349,7 +510,7 @@ export const createEnvironment = (
         kind: "Operator",
         name: `${declaration.name}${suffix}`,
         params: [
-          ...(isParameterDependent(declaration) ? instanceParams : []),
+          ...(isParameterDependent(declaration) ? instance.params : []),
           ...substitution.params,
         ],
         body: substitution.body,
@@ -360,7 +521,7 @@ export const createEnvironment = (
     });
     const copies: Definition[] = [];
     const instantiation = createInstantiation({
-      params: instanceParams,
+      params: instance.params,
       substitutions: new Map(
         declarations.map((declaration): [string, Expression] => [
           declaration.name,
@@ -374,7 +535,7 @@ export const createEnvironment = (
             : {
                 kind: "Apply",
                 operator: `${declaration.name}${suffix}`,
-                args: getLocalArguments(instanceParams, location),
+                args: getLocalArguments(instance.params, location),
                 location,
                 resolution: LOCAL_RESOLUTION,
               },
@@ -393,6 +554,7 @@ export const createEnvironment = (
         );
         return key;
       },
+      createName,
     });
     const declared = new Set(declarations.map((declaration) => declaration.name));
     const aliases = [...linked.exported]
@@ -400,7 +562,7 @@ export const createEnvironment = (
       .map(([name, symbol]) => {
         const key = instantiation.getKey(symbol.key);
         const own = getArguments(symbol.arity);
-        const params = [...instanceParams, ...own];
+        const params = [...instance.params, ...own];
         return createLocalAlias(
           instance.name === undefined ? name : `${instance.name}!${name}`,
           key,
@@ -418,61 +580,139 @@ export const createEnvironment = (
       return definition ? [{ ...definition, name }] : [];
     });
 
-  const linkModule = (parsed: Module): LinkedModule => {
-    const visible: Symbols = new Map(
-      CORE_OPERATORS.map((operator) => [
+  const linkModule = (unlinked: Module, scope: ModuleScope): LinkedModule => {
+    const parsed = overrideDefinitions(unlinked, options.loadClass?.(unlinked.name));
+    const visible: Symbols = new Map([
+      ...CORE_OPERATORS.map((operator): [string, ModuleSymbol] => [
         operator.name,
         { key: operator.name, arity: operator.arity },
       ]),
-    );
+      ...scope.symbols,
+    ]);
     const exported: Symbols = new Map();
+    const modules = new Map<string, LinkedModule>();
+    const extended: LinkedModule[] = [];
     const constants = [...parsed.constants];
-    const variables = [...parsed.variables];
+    const variables = parsed.variables.map((variable) => variable.name);
+    const variableLocations = parsed.variables.map((variable) => variable.location);
     const addSymbols = (symbols: Symbols, isExported: boolean) =>
       symbols.forEach((symbol, name) => {
         visible.set(name, symbol);
         if (isExported) exported.set(name, symbol);
       });
-    parsed.outer?.extends.forEach((name) =>
-      addSymbols(addStandardModule(name) ?? getLinkedModule(name).exported, false),
-    );
-    parsed.outer?.symbols.forEach((symbol) =>
-      visible.set(symbol.name, { key: getOuterKey(parsed, symbol.name), arity: symbol.arity }),
-    );
     parsed.extends.forEach((name) => {
-      const standardSymbols = addStandardModule(name);
+      const nested = scope.modules.get(name);
+      const standardSymbols = nested ? undefined : getStandardSymbols(name);
       if (standardSymbols) {
         addSymbols(standardSymbols, true);
         return;
       }
-      const linked = getLinkedModule(name);
+      const linked = nested ?? getLinkedModule(name, parsed.name);
       constants.push(
         ...linked.constants.filter((constant) =>
           constants.every((existing) => existing.name !== constant.name),
         ),
       );
-      variables.push(...linked.variables.filter((variable) => !variables.includes(variable)));
+      linked.variables.forEach((variable, index) => {
+        if (variables.includes(variable)) return;
+        variables.push(variable);
+        variableLocations.push(linked.variableLocations[index]);
+      });
       addSymbols(linked.exported, true);
+      linked.modules.forEach((module, moduleName) => modules.set(moduleName, module));
+      extended.push(linked);
     });
     parsed.constants.forEach((constant) =>
-      exported.set(constant.name, { key: constant.name, arity: constant.arity }),
+      exported.set(constant.name, {
+        key: constant.name,
+        arity: constant.arity,
+        declaration: "Constant",
+      }),
+    );
+    parsed.variables.forEach((variable) =>
+      exported.set(variable.name, { key: variable.name, arity: 0, declaration: "Variable" }),
     );
-    parsed.variables.forEach((variable) => exported.set(variable, { key: variable, arity: 0 }));
     const isParameterFree = constants.length === 0 && variables.length === 0;
-    const getKey = (definition: Definition) => getDefinitionKey(parsed, definition.name);
+    const getKey = (definition: Definition) =>
+      parsed === root ? definition.name : `${definition.name}${KEY_SEPARATOR}${scope.id}`;
+    const importedAt = new Map<string, SourceLocation>();
     const getUnit = (module: Module) => ({
       imported: visible,
+      importedAt,
       definitions: new Map(module.definitions.map((definition) => [definition.name, definition])),
       getKey,
     });
-    parsed.instances.forEach((instance) =>
-      addSymbols(
-        instantiate(instance, parsed, getUnit(parsed), isParameterFree),
-        !instance.isLocal,
-      ),
-    );
+    const getVisibleModules = () => new Map([...scope.modules, ...modules]);
+    const getSymbolsBefore = (location: SourceLocation): Symbols =>
+      new Map([
+        ...visible,
+        ...[
+          ...parsed.constants.map((constant) => ({ ...constant, kind: "Constant" as const })),
+          ...parsed.variables.map((variable) => ({ ...variable, kind: "Variable" as const })),
+        ]
+          .filter((declaration) => isBefore(declaration.location, location))
+          .map((declaration): [string, ModuleSymbol] => [
+            declaration.name,
+            { key: declaration.name, arity: declaration.arity, declaration: declaration.kind },
+          ]),
+        ...parsed.definitions
+          .filter((definition) => isBefore(definition.location, location))
+          .map((definition): [string, ModuleSymbol] => [
+            definition.name,
+            { key: getKey(definition), arity: getArity(definition) },
+          ]),
+      ]);
+    const linkNested = (nested: Module) => {
+      const visibleModules = getVisibleModules();
+      if (visibleModules.has(nested.name)) throw createModuleRedefinedError(nested);
+      scope.nested.push(nested);
+      const linked = linkModule(nested, {
+        id: `${scope.id}/${nested.name}`,
+        symbols: getSymbolsBefore(nested.location),
+        modules: visibleModules,
+        nested: scope.nested,
+      });
+      modules.set(nested.name, linked);
+      if (!nestedModules.has(nested.name)) nestedModules.set(nested.name, linked);
+    };
+    [
+      ...parsed.instances.map((instance) => ({
+        location: instance.location,
+        link: () => {
+          const symbols = instantiate(
+            instance,
+            parsed,
+            getUnit(parsed),
+            isParameterFree,
+            getVisibleModules().get(instance.module),
+          );
+          symbols.forEach((_, name) => {
+            if (!visible.has(name)) importedAt.set(name, instance.location);
+          });
+          addSymbols(symbols, !instance.isLocal);
+        },
+      })),
+      ...parsed.modules.map((nested) => ({
+        location: nested.location,
+        link: () => linkNested(nested),
+      })),
+    ]
+      .sort((left, right) => (isBefore(left.location, right.location) ? -1 : 1))
+      .forEach((unit) => unit.link());
+    checkRedefinitions(parsed, getUnit(parsed));
+    const isInstancedAfterDefinition = (nested: Module) => {
+      const first = parsed.instances.find((instance) => instance.module === nested.name);
+      return first !== undefined && isBefore(nested.location, first.location);
+    };
+    const getLetModule = (instance: Instance) => {
+      const own = parsed.modules.find((nested) => nested.name === instance.module);
+      if (!own) return getVisibleModules().get(instance.module);
+      return isInstancedAfterDefinition(own) ? modules.get(own.name) : undefined;
+    };
     const module = resolveModuleSubexpressions(
-      withLetInstances(parsed, instantiateLocally),
+      withLetInstances(parsed, (instance, lets) =>
+        instantiateLocally(instance, lets, parsed.name, getLetModule(instance)),
+      ),
       getAvailableDefinitions(visible),
     );
     resolveModule(module, getUnit(module));
@@ -484,12 +724,26 @@ export const createEnvironment = (
       visible.set(definition.name, symbol);
       if (!definition.isLocal) exported.set(definition.name, symbol);
     });
-    const linked = { module, constants, variables, visible, exported };
-    linkedModules.set(parsed.name, linked);
+    checkModuleLevels(module, {
+      constants: new Set(constants.map((constant) => constant.name)),
+      variables: new Set(variables),
+      getDefinition: (symbol) => definitions.get(visible.get(symbol)?.key ?? symbol),
+    });
+    const linked = {
+      module,
+      constants,
+      variables,
+      variableLocations,
+      visible,
+      exported,
+      modules,
+      extended,
+    };
+    linkedList.push(linked);
     return linked;
   };
 
-  const linkedRoot = linkModule(root);
+  const linkedRoot = linkTopLevel(root).linked;
   const getRootKey = (name: string) => linkedRoot.visible.get(name)?.key ?? name;
   linkedRoot.visible.forEach((symbol, name) => {
     const definition = definitions.get(symbol.key);
@@ -497,47 +751,80 @@ export const createEnvironment = (
   });
 
   const assumptions: Assumption[] = [];
-  const addAssumptions = (module: Module, visited: Set<string>) => {
-    if (visited.has(module.name)) return;
-    visited.add(module.name);
-    module.extends.forEach((name) => {
-      const linked = linkedModules.get(name);
-      if (linked) addAssumptions(linked.module, visited);
-    });
-    assumptions.push(...module.assumptions);
+  const addAssumptions = (linked: LinkedModule, visited: Set<LinkedModule>) => {
+    if (visited.has(linked)) return;
+    visited.add(linked);
+    linked.extended.forEach((extended) => addAssumptions(extended, visited));
+    assumptions.push(...linked.module.assumptions);
   };
-  addAssumptions(linkedRoot.module, new Set());
+  addAssumptions(linkedRoot, new Set());
   const declaredConstants = linkedRoot.constants.map((constant) => constant.name);
   const variables = linkedRoot.variables;
 
-  const getScopedKeys = (item: { name: string; module?: string }): string[] => {
+  const getScopedKeys = (item: { name: string; module?: string }) => {
     if (item.module === undefined) return [item.name, getRootKey(item.name)];
     if (item.module === root.name || declaredConstants.includes(item.name)) return [];
-    return [linkedModules.get(item.module)?.visible.get(item.name)?.key ?? item.name];
+    const linked = linkedModules.get(item.module) ?? nestedModules.get(item.module);
+    return [linked?.visible.get(item.name)?.key ?? item.name];
+  };
+  const getKeyArity = (key: string) => {
+    const definition = definitions.get(key);
+    return definition?.kind === "Operator"
+      ? definition.params.length
+      : (linkedRoot.constants.find((constant) => constant.name === key)?.arity ?? 0);
   };
   const constants = new Map<string, Value>();
+  const operatorKeys = new Set<string>();
+  const setOperator = (key: string, operator: Builtin) => {
+    builtins.set(key, operator);
+    definitions.delete(key);
+    constants.delete(key);
+    operatorKeys.add(key);
+  };
   config.constants
     .filter((assignment) => assignment.args === undefined)
     .forEach((assignment) => {
       const value = toValue(assignment.value);
-      getScopedKeys(assignment).forEach((key) => constants.set(key, value));
+      getScopedKeys(assignment).forEach((key) => {
+        const arity = getKeyArity(key);
+        if (arity === 0) constants.set(key, value);
+        else
+          setOperator(key, {
+            kind: "Builtin",
+            name: key,
+            arity,
+            evaluate: () => value,
+            evaluateUnary: undefined,
+            evaluateBinary: undefined,
+            isLazy: true,
+          });
+      });
     });
-  const operatorConstants = new Map<string, [Value[], Value][]>();
+  const tables = new Map<string, { name: string; module?: string; rows: [Value[], Value][] }>();
   config.constants.forEach((assignment) => {
     if (assignment.args === undefined) return;
-    const rows = operatorConstants.get(assignment.name) ?? [];
-    if (rows.length > 0 && rows[0][0].length !== assignment.args.length) {
+    const tableKey = `${assignment.module ?? ""}!${assignment.name}`;
+    const table = tables.get(tableKey) ?? {
+      name: assignment.name,
+      module: assignment.module,
+      rows: [],
+    };
+    if (table.rows.length > 0 && table.rows[0][0].length !== assignment.args.length) {
       throw new TlaConfigError(
-        `The operator ${assignment.name} is assigned values with inconsistent arities`,
+        `The arity of the operator ${assignment.name} is inconsistent in the configuration file.`,
       );
     }
-    rows.push([assignment.args.map(toValue), toValue(assignment.value)]);
-    operatorConstants.set(assignment.name, rows);
-  });
-  operatorConstants.forEach((rows, name) => {
-    builtins.set(name, createOperatorConstant(name, rows));
-    constants.delete(name);
+    table.rows.push([assignment.args.map(toValue), toValue(assignment.value)]);
+    tables.set(tableKey, table);
   });
+  tables.forEach((table) =>
+    getScopedKeys(table).forEach((key) =>
+      setOperator(
+        key,
+        createOperatorConstant(table.name, getKeyArity(key) || table.rows[0][0].length, table.rows),
+      ),
+    ),
+  );
   const substitutions = new Map(
     config.substitutions.flatMap((substitution) =>
       getScopedKeys(substitution).map((key): [string, string] => [
@@ -546,8 +833,47 @@ export const createEnvironment = (
       ]),
     ),
   );
+  config.substitutions
+    .filter((substitution) => substitution.module === undefined)
+    .forEach((substitution) => {
+      const name = substitution.name;
+      const target = substitution.target;
+      if (!declaredConstants.includes(name) && !linkedRoot.visible.has(name)) {
+        throw new TlaConfigError(
+          `In the configuration file, the identifier ${name} does not appear in the specification.`,
+        );
+      }
+      if (config.substitutions.some((other) => other.name === target)) {
+        throw new TlaConfigError(
+          `In the configuration file, the identifier ${target} appears\non the right-hand side of a <- after already appearing on the\nleft-hand side of one.`,
+        );
+      }
+      const targetKey = getRootKey(target);
+      const definition = definitions.get(targetKey);
+      const isDefined =
+        definition !== undefined ||
+        builtins.has(targetKey) ||
+        constants.has(targetKey) ||
+        declaredConstants.includes(target) ||
+        variables.includes(target);
+      if (!isDefined) {
+        throw new TlaConfigError(
+          `The configuration file substitutes for ${name} with the undefined identifier ${target}.`,
+        );
+      }
+      if (
+        definition?.kind === "Operator" &&
+        definition.params.length !==
+          (linkedRoot.constants.find((constant) => constant.name === name)?.arity ??
+            linkedRoot.visible.get(name)?.arity)
+      ) {
+        throw new TlaConfigError(
+          `The configuration file substitutes for ${name} with ${target} of different number of arguments.`,
+        );
+      }
+    });
   declaredConstants.forEach((name) => {
-    if (!constants.has(name) && !substitutions.has(name) && !operatorConstants.has(name)) {
+    if (!constants.has(name) && !substitutions.has(name) && !operatorKeys.has(name)) {
       throw new TlaConfigError(`The constant ${name} is not assigned a value by the configuration`);
     }
   });
@@ -561,12 +887,26 @@ export const createEnvironment = (
     variables,
     variableIndex: getVariableIndex(
       variables,
-      [...linkedModules.values()].flatMap((linked) => linked.module.variables),
+      linkedList.flatMap((linked) => linked.module.variables.map((variable) => variable.name)),
     ),
     definitionValues: new Map(),
     constantLevels: new Map(),
     evaluators: new WeakMap(),
   };
+  checkInstances(instanceChecks, (name) => {
+    const linked = linkedModules.get(name) ?? nestedModules.get(name) ?? linkedRoot;
+    return {
+      constants: linked.constants,
+      variables: linked.variables,
+      definitions: [
+        ...new Set(
+          [...linked.visible.values()].flatMap((symbol) => definitions.get(symbol.key) ?? []),
+        ),
+      ],
+      assumptions: linked.module.assumptions.map((assumption) => assumption.expression),
+      getDefinition: (symbol) => definitions.get(linked.visible.get(symbol)?.key ?? symbol),
+    };
+  });
   substitutions.forEach((target, name) => {
     const definition = definitions.get(target);
     if (
@@ -579,5 +919,10 @@ export const createEnvironment = (
       );
     }
   });
-  return { environment, assumptions };
+  return {
+    environment,
+    assumptions,
+    variableLocations: linkedRoot.variableLocations,
+    instanceActions,
+  };
 };