tla-ts 0.0.4-dev.702eb98 → 0.0.4-dev.7b5087a

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.
package/src/run-cli.ts CHANGED
@@ -5,6 +5,7 @@ import {
5
5
  readFileSync,
6
6
  readSync,
7
7
  realpathSync,
8
+ rmSync,
8
9
  writeFileSync,
9
10
  } from "node:fs";
10
11
  import { basename, delimiter, dirname, isAbsolute, join, resolve } from "node:path";
@@ -43,10 +44,28 @@ import {
43
44
  import { EXIT_STATUS, setExitCode } from "./exit-codes";
44
45
  import type { LineRange } from "./obligations/generate";
45
46
  import { getAtPrefix, getLocusText } from "./obligations/expression";
46
- import { formatSummary, getObligations, WHOLE_MODULE, type ModuleObligations } from "./obligations";
47
+ import {
48
+ formatSummary,
49
+ getObligations,
50
+ WHOLE_MODULE,
51
+ type ModuleObligations,
52
+ type PrintedObligation,
53
+ } from "./obligations";
54
+ import { format, renderDoc } from "./obligations/format";
55
+ import { printSequent } from "./obligations/printer";
47
56
  import { check } from "./parallel";
48
57
  import { parseModule } from "./parser";
49
- import { isProveBackend, prove, PROVE_BACKENDS, type ProofStatus } from "./prove/prove";
58
+ import {
59
+ encodeProofTheory,
60
+ formatNormalized,
61
+ isProveBackend,
62
+ prove,
63
+ proveObligations,
64
+ PROVE_BACKENDS,
65
+ type ProofAttempt,
66
+ type ProofStatus,
67
+ } from "./prove/prove";
68
+ import { TLAPS_MODULE } from "./prove/tlaps-module";
50
69
  import type { StateDump } from "./state-graph";
51
70
  import {
52
71
  formatProbability,
@@ -55,6 +74,14 @@ import {
55
74
  getOutDegreeSummary,
56
75
  } from "./tlc-summary";
57
76
  import { getTlapmPaths } from "./prove/tlapm/tlapm";
77
+ import {
78
+ getKnownResults,
79
+ loadFingerprints,
80
+ saveFingerprints,
81
+ saveHistory,
82
+ updateFingerprints,
83
+ type FingerprintTable,
84
+ } from "./tlapm-cache";
58
85
  import type { SanySpecification } from "./sany-generator";
59
86
  import { SANY_174_STANDARD_MODULES, SANY_STANDARD_MODULES } from "./sany-modules";
60
87
  import { getSanyModuleName, getSanyReport, type SanyModuleOrigin } from "./sany-report";
@@ -102,16 +129,29 @@ const CHECK_COMMAND = defineCommand("tla-ts <Spec.tla|Spec.cfg|glob>... {options
102
129
  { flag: "-workers <count|auto>" },
103
130
  ]);
104
131
 
105
- const OBLIGATIONS_COMMAND = defineCommand("tla-ts prove {options} <Module.tla|glob>...", [
106
- { flag: "-N", isRequired: true },
132
+ // -k changes nothing, as in tlapm.
133
+ const TLAPM_COMMAND = defineCommand("tla-ts tlapm {options} <Module.tla|glob>...", [
134
+ { flag: "-N" },
135
+ { flag: "--summary" },
136
+ { flag: "--strict" },
107
137
  { flag: "--toolbox <start> <end>" },
108
138
  { flag: "--line <num>" },
109
139
  { flag: "--printallobs" },
110
- { flag: "--summary" },
111
- { flag: "--strict" },
140
+ { flag: "--threads <num>" },
141
+ { flag: "--version" },
112
142
  { flag: "-I <directory>", isRepeatable: true },
143
+ { flag: "-k" },
144
+ { flag: "--noproving" },
145
+ { flag: "--nofp" },
146
+ { flag: "--nofpl <start> <end>" },
147
+ { flag: "--safefp" },
148
+ { flag: "--cleanfp" },
149
+ { flag: "--usefp <file>" },
150
+ { flag: "--cache-dir <directory>" },
113
151
  ]);
114
152
 
153
+ const TLAPM_INTEGER_OPTIONS = new Set(["--toolbox", "--line", "--threads", "--nofpl"]);
154
+
115
155
  const PROVE_COMMAND = defineCommand("tla-ts prove {options} <Module.tla|glob>...", [
116
156
  { flag: `--backend <${PROVE_BACKENDS.join("|")}>` },
117
157
  { flag: "-I <directory>", isRepeatable: true },
@@ -173,7 +213,7 @@ const XML_EXPORT_USAGE = (() => {
173
213
  const USAGE = [
174
214
  `Usage: ${CHECK_COMMAND.usage}`,
175
215
  ` ${PROVE_COMMAND.usage}`,
176
- ` ${OBLIGATIONS_COMMAND.usage}`,
216
+ ` ${TLAPM_COMMAND.usage}`,
177
217
  " tla-ts [<JVM option>]... tlc2.TLC <TLC option>... <Spec>",
178
218
  " (-cp tla2tools.jar or -Dtla-ts.tlc=1.7.4 picks the TLC to reproduce)",
179
219
  " tla-ts [<JVM option>]... tla2sany.xml.XMLExporter [-I <directory>]... [-o] [-t] [-r] [-u] <Module.tla>",
@@ -1065,17 +1105,27 @@ const readModule = (path: string) =>
1065
1105
  const printToolboxMessage = (fields: string[]) =>
1066
1106
  console.error(`@!!BEGIN\n${fields.map((field) => `@!!${field}\n`).join("")}@!!END\n`);
1067
1107
 
1068
- const TLAPM_VERSION = "5f5037f";
1108
+ const printObligationMessage = (obligation: PrintedObligation, status: string, fields: string[]) =>
1109
+ printToolboxMessage([
1110
+ "type:obligation",
1111
+ `id:${obligation.id}`,
1112
+ `loc:${obligation.location}`,
1113
+ `status:${status}`,
1114
+ ...fields,
1115
+ ]);
1116
+
1117
+ const TLAPM_VERSION = "9ed0376";
1069
1118
 
1070
1119
  const quoteArgument = (arg: string) =>
1071
1120
  /^[+,\-./0-9:=@A-Z_a-z]+$/.test(arg) ? arg : `'${arg.replaceAll("'", "'\\''")}'`;
1072
1121
 
1073
1122
  const printToolboxHeader = (args: string[]) =>
1074
1123
  console.log(
1075
- `\n\\* TLAPM version ${TLAPM_VERSION}\n\\* launched at ${formatTlcDate(new Date())} with command line:\n\\* ${["tla-ts", "prove", ...args].map(quoteArgument).join(" ")}\n`,
1124
+ `\n\\* TLAPM version ${TLAPM_VERSION}\n\\* launched at ${formatTlcDate(new Date())} with command line:\n\\* ${["tla-ts", "tlapm", ...args].map(quoteArgument).join(" ")}\n`,
1076
1125
  );
1077
1126
 
1078
- const STRICT_EXIT_STATUS = { incomplete: 11, emptyTarget: 12 };
1127
+ // The most severe first, as tlapm exits with the most severe status --strict noted.
1128
+ const STRICT_EXIT_STATUS = { failed: 10, incomplete: 11, emptyTarget: 12 };
1079
1129
 
1080
1130
  const checkStrictly = (result: ModuleObligations, isTargeted: boolean, isSummary: boolean) => {
1081
1131
  const summary = result.summary;
@@ -1103,6 +1153,19 @@ const checkStrictly = (result: ModuleObligations, isTargeted: boolean, isSummary
1103
1153
 
1104
1154
  const TLAPM_FAILURE_STATUS = 3;
1105
1155
 
1156
+ // What tlapm prints when a module has unproved obligations outside toolbox mode, OCaml's backtrace
1157
+ // included.
1158
+ const UNPROVED_ENDING = [
1159
+ ' tlapm ending abnormally with Failure("backend errors: there are unproved obligations")',
1160
+ 'Raised at Stdlib.failwith in file "stdlib.ml", line 29, characters 17-33',
1161
+ 'Called from Tlapm_lib.process_module in file "src/tlapm_lib.ml", lines 492-493, characters 12-37',
1162
+ 'Called from Tlapm_lib.main.f in file "src/tlapm_lib.ml", line 640, characters 23-43',
1163
+ 'Called from Stdlib__List.fold_left in file "list.ml", line 125, characters 24-34',
1164
+ 'Called from Tlapm_lib.main in file "src/tlapm_lib.ml", line 643, characters 13-40',
1165
+ 'Called from Tlapm_lib.init in file "src/tlapm_lib.ml", line 659, characters 8-59',
1166
+ "",
1167
+ ].join("\n");
1168
+
1106
1169
  const generateObligations = (generate: () => ModuleObligations[]) => {
1107
1170
  try {
1108
1171
  return generate();
@@ -1166,12 +1229,122 @@ const proveModules = (args: string[]) => {
1166
1229
  );
1167
1230
  };
1168
1231
 
1169
- const runProve = (args: string[]) => {
1170
- if (!args.includes("-N") && !args.includes("--summary")) return proveModules(args);
1171
- const parsed = OBLIGATIONS_COMMAND.parse(args);
1172
- const unsupported = parsed.unknown[0];
1232
+ // Toolbox.print_res_aux: what one method concluded, with the obligation it failed on, as Prep
1233
+ // normalized it. Only a new SMT failure notes the solver's answer.
1234
+ const printAttempt = (obligation: PrintedObligation, attempt: ProofAttempt) => {
1235
+ const limit = attempt.method.timeLimitMs;
1236
+ const used =
1237
+ attempt.timeUsedMs === undefined
1238
+ ? ""
1239
+ : `; time-used: ${(attempt.timeUsedMs / 1000).toFixed(1)} (${Math.round((100 * attempt.timeUsedMs) / limit)}%)`;
1240
+ const times =
1241
+ limit === 0
1242
+ ? ""
1243
+ : `time-limit: ${limit === Infinity ? "inf" : Number((limit / 1000).toPrecision(6))}${used}`;
1244
+ const method = [attempt.method.tactic, times].filter(Boolean).join("; ");
1245
+ const isSmt = attempt.method.prover === "smt" || attempt.method.prover === "z3";
1246
+ const note =
1247
+ isSmt && attempt.reason === "false" && attempt.verdict
1248
+ ? `(* SMT failed with status = ${attempt.verdict}\n *)\n`
1249
+ : "";
1250
+ printObligationMessage(obligation, attempt.isProved ? "proved" : "failed", [
1251
+ `prover:${attempt.method.prover}`,
1252
+ ...(method === "" ? [] : [`meth:${method}`]),
1253
+ ...(attempt.reason === undefined ? [] : [`reason:${attempt.reason}`]),
1254
+ `already:${attempt.isReused}`,
1255
+ ...(attempt.isProved
1256
+ ? []
1257
+ : [
1258
+ `obl:${attempt.isReused ? "" : `\n${note}`}${formatNormalized(obligation, attempt.isReused)}`,
1259
+ ]),
1260
+ ]);
1261
+ };
1262
+
1263
+ // tlapm fails with Method.Fail an obligation that is an error, and one no method was tried on.
1264
+ const printFailure = (obligation: PrintedObligation, reason: string) =>
1265
+ printObligationMessage(obligation, "failed", [
1266
+ "prover:fail",
1267
+ "meth:time-limit: inf",
1268
+ `reason:${reason}`,
1269
+ "already:false",
1270
+ `obl:${obligation.text}`,
1271
+ ]);
1272
+
1273
+ interface ProvingSettings {
1274
+ isToolbox: boolean;
1275
+ isProving: boolean;
1276
+ workers: number;
1277
+ isFingerprinted: (obligation: PrintedObligation) => boolean;
1278
+ fingerprints: FingerprintTable;
1279
+ }
1280
+
1281
+ // Tlapm_lib.process_obs: proves a module's obligations, printing each result in toolbox mode, and
1282
+ // writes the theory of their proofs and the fingerprints. Unless --noproving, it then prints those
1283
+ // tlapm couldn't prove, the last first. Returns whether some obligation failed.
1284
+ const proveModule = async (
1285
+ result: ModuleObligations,
1286
+ theoryPath: string,
1287
+ fingerprintsPath: string,
1288
+ sources: string[],
1289
+ settings: ProvingSettings,
1290
+ ) => {
1291
+ saveHistory(fingerprintsPath, sources);
1292
+ const results = getKnownResults(settings.fingerprints);
1293
+ const reports = await proveObligations(result.obligations, {
1294
+ workers: settings.workers,
1295
+ results,
1296
+ isFingerprinted: settings.isFingerprinted,
1297
+ isProving: settings.isProving,
1298
+ onReport: (report, obligation) => {
1299
+ if (!settings.isToolbox) return;
1300
+ if (report.obligation.status === "trivial")
1301
+ return printObligationMessage(obligation, "trivial", ["prover:tlapm", "already:false"]);
1302
+ if (obligation.kind.kind === "Error") return printFailure(obligation, "user error");
1303
+ report.attempts.forEach((attempt) => printAttempt(obligation, attempt));
1304
+ },
1305
+ });
1306
+ writeFileSync(theoryPath, encodeProofTheory(result.name, reports, result.obligations));
1307
+ console.log(`(* created new ${JSON.stringify(theoryPath)} *)`);
1308
+ updateFingerprints(settings.fingerprints, results);
1309
+ saveFingerprints(settings.fingerprints, fingerprintsPath);
1310
+ console.log(`(* fingerprints written in ${JSON.stringify(fingerprintsPath)} *)`);
1311
+ if (!settings.isProving) return false;
1312
+ const unproved = reports.flatMap((report, index) =>
1313
+ "reason" in report.obligation ? [{ report, obligation: result.obligations[index] }] : [],
1314
+ );
1315
+ if (settings.isToolbox) {
1316
+ unproved
1317
+ .filter(
1318
+ (entry) => entry.report.attempts.length === 0 && entry.obligation.kind.kind !== "Error",
1319
+ )
1320
+ .forEach((entry) => printFailure(entry.obligation, "unexpected error"));
1321
+ }
1322
+ unproved
1323
+ .toReversed()
1324
+ .forEach((entry) =>
1325
+ console.error(
1326
+ `${getAtPrefix(entry.obligation.locus)}${renderDoc(format("[ERROR]: @[<v2>Could not prove or check:@,%a@]", printSequent(entry.obligation.sequent)), 35)}`,
1327
+ ),
1328
+ );
1329
+ const total = `${result.obligations.length} obligation${result.obligations.length > 1 ? "s" : ""}`;
1330
+ console.error(
1331
+ unproved.length === 0
1332
+ ? `${getAtPrefix(result.location)}[INFO]: All ${total} proved.`
1333
+ : `${getAtPrefix(result.location)}[ERROR]: ${unproved.length}/${total} failed.\nThere were backend errors processing module \`${JSON.stringify(result.name)}\`.`,
1334
+ );
1335
+ return unproved.length > 0;
1336
+ };
1337
+
1338
+ // tla-ts tlapm: tlapm's command line, proving with tla-ts's backends. -N and --summary only
1339
+ // generate the obligations.
1340
+ const runTlapm = async (args: string[]) => {
1341
+ const parsed = TLAPM_COMMAND.parse(args);
1342
+ const isProcessing = !parsed.has("-N") && !parsed.has("--summary");
1343
+ const unsupported =
1344
+ parsed.unknown[0] ??
1345
+ (isProcessing && parsed.has("--printallobs") ? "--printallobs" : undefined);
1173
1346
  if (unsupported !== undefined) {
1174
- console.error(`Error: tla-ts prove does not support the tlapm option ${unsupported}.`);
1347
+ console.error(`Error: tla-ts tlapm does not support the tlapm option ${unsupported}.`);
1175
1348
  return 1;
1176
1349
  }
1177
1350
  if (parsed.incomplete) {
@@ -1179,12 +1352,18 @@ const runProve = (args: string[]) => {
1179
1352
  return 1;
1180
1353
  }
1181
1354
  const nonInteger = parsed.options.find(
1182
- (option) => option.name !== "-I" && option.values.some((value) => !/^-?\d+$/.test(value)),
1355
+ (option) =>
1356
+ TLAPM_INTEGER_OPTIONS.has(option.name) &&
1357
+ option.values.some((value) => !/^-?\d+$/.test(value)),
1183
1358
  );
1184
1359
  if (nonInteger) {
1185
1360
  console.error(`Error: option '${nonInteger.name}' expects an integer.`);
1186
1361
  return 1;
1187
1362
  }
1363
+ if (parsed.has("--version")) {
1364
+ console.log(TLAPM_VERSION);
1365
+ return EXIT_STATUS.success;
1366
+ }
1188
1367
  const files = expandGlobs(parsed.positionals);
1189
1368
  const modulePaths = files.map((path) => (path.endsWith(".tla") ? path : `${path}.tla`));
1190
1369
  if (modulePaths.length === 0) {
@@ -1201,7 +1380,7 @@ const runProve = (args: string[]) => {
1201
1380
  return range;
1202
1381
  }, WHOLE_MODULE);
1203
1382
  // tlapm searches the current directory and each module's, then its library, then each -I
1204
- // directory, the last given first.
1383
+ // directory, the last given first. Without tlapm, TLAPS is the copy tla-ts bundles.
1205
1384
  const tlapmLibrary = getTlapmLibrary();
1206
1385
  const includes = parsed.options.flatMap((option) => (option.name === "-I" ? option.values : []));
1207
1386
  const directories = modulePaths.reduce(
@@ -1209,6 +1388,7 @@ const runProve = (args: string[]) => {
1209
1388
  [".", ...(tlapmLibrary ? [tlapmLibrary] : []), ...includes.toReversed()],
1210
1389
  );
1211
1390
  // tlapm names each file it reads by joining a search directory and the name, as in ./Module.tla.
1391
+ const moduleNames = new Set<string>();
1212
1392
  const results = generateObligations(() => {
1213
1393
  const missingIndex = modulePaths.findIndex((path) => !existsSync(path));
1214
1394
  if (missingIndex !== -1) {
@@ -1218,8 +1398,13 @@ const runProve = (args: string[]) => {
1218
1398
  }
1219
1399
  return getObligations(
1220
1400
  modulePaths.map((path) => ({ file: `./${path}`, source: readFileSync(path, "utf8") })),
1221
- (name) =>
1222
- directories.map((directory) => readModule(`${directory}/${name}.tla`)).find(Boolean),
1401
+ (name) => {
1402
+ moduleNames.add(name);
1403
+ return (
1404
+ directories.map((directory) => readModule(`${directory}/${name}.tla`)).find(Boolean) ??
1405
+ (name === "TLAPS" ? { file: "TLAPS.tla", source: TLAPS_MODULE } : undefined)
1406
+ );
1407
+ },
1223
1408
  {
1224
1409
  lines,
1225
1410
  onWarning: (warning) => {
@@ -1234,26 +1419,83 @@ const runProve = (args: string[]) => {
1234
1419
  );
1235
1420
  });
1236
1421
  if (!results) return TLAPM_FAILURE_STATUS;
1237
- const failures = results.flatMap((result) => {
1422
+ const cacheDirectory =
1423
+ parsed.get("--cache-dir")?.[0] ?? process.env.TLAPM_CACHE_DIR ?? ".tlacache";
1424
+ const forgottenLines = parsed.get("--nofpl")?.map(Number) ?? [0, 0];
1425
+ const settings: ProvingSettings = {
1426
+ isToolbox,
1427
+ isProving: !parsed.has("--noproving"),
1428
+ workers: Math.max(1, Number(parsed.get("--threads")?.[0] ?? availableParallelism())),
1429
+ isFingerprinted: (obligation) =>
1430
+ !parsed.has("--nofp") &&
1431
+ !(
1432
+ obligation.locus &&
1433
+ obligation.locus.startLine >= forgottenLines[0] &&
1434
+ obligation.locus.endLine <= forgottenLines[1]
1435
+ ),
1436
+ fingerprints: new Map(),
1437
+ };
1438
+ const statuses: number[] = [];
1439
+ for (const [index, result] of results.entries()) {
1440
+ // Tlapm_lib.mkdir_tlaps, then --cleanfp removes the fingerprints file or tlapm loads the one
1441
+ // --usefp names, the module's own by default.
1442
+ const directory = `${cacheDirectory}/${result.name}.tlaps`;
1443
+ const fingerprintsPath = `${directory}/fingerprints`;
1444
+ const loadedPath = parsed.get("--usefp")?.[0] ?? fingerprintsPath;
1445
+ mkdirSync(directory, { recursive: true });
1446
+ if (parsed.has("--cleanfp")) {
1447
+ if (existsSync(fingerprintsPath)) {
1448
+ rmSync(fingerprintsPath);
1449
+ console.log(`(* fingerprints file ${JSON.stringify(fingerprintsPath)} removed *)`);
1450
+ }
1451
+ } else if (existsSync(loadedPath) && result.summary.total !== 0) {
1452
+ console.log(
1453
+ parsed.has("--nofp")
1454
+ ? `(* will not use fingerprints (because of option \`--nofp\`), but will now load fingerprints from the file \`${loadedPath}\`, in order to overwrite with the new fingerprints, and then save the results at the end. *)`
1455
+ : `(* loading fingerprints in ${JSON.stringify(loadedPath)} *)`,
1456
+ );
1457
+ loadFingerprints(settings.fingerprints, loadedPath, parsed.has("--safefp"));
1458
+ }
1238
1459
  if (parsed.has("--summary")) console.log(formatSummary(result));
1239
1460
  if (isToolbox) {
1240
1461
  result.obligations.forEach((obligation) =>
1241
- printToolboxMessage([
1242
- "type:obligation",
1243
- `id:${obligation.id}`,
1244
- `loc:${obligation.location}`,
1245
- "status:to be proved",
1246
- ...(parsed.has("--printallobs") ? [`obl:${obligation.text}`] : []),
1247
- ]),
1462
+ printObligationMessage(
1463
+ obligation,
1464
+ "to be proved",
1465
+ parsed.has("--printallobs") ? [`obl:${obligation.text}`] : [],
1466
+ ),
1248
1467
  );
1249
1468
  printToolboxMessage(["type:obligationsnumber", `count:${result.obligations.length}`]);
1250
1469
  }
1251
- if (!parsed.has("--strict")) return [];
1252
- return checkStrictly(result, lines.start > 0 || lines.end < Infinity, parsed.has("--summary"));
1253
- });
1254
- return failures.includes(STRICT_EXIT_STATUS.incomplete)
1255
- ? STRICT_EXIT_STATUS.incomplete
1256
- : (failures[0] ?? EXIT_STATUS.success);
1470
+ if (parsed.has("--strict"))
1471
+ statuses.push(
1472
+ ...checkStrictly(result, lines.start > 0 || lines.end < Infinity, parsed.has("--summary")),
1473
+ );
1474
+ if (!isProcessing) continue;
1475
+ // tlapm copies into the history the source in the current directory of each module it has
1476
+ // read so far.
1477
+ const sources = [
1478
+ ...moduleNames,
1479
+ ...results.slice(0, index + 1).map((innerResult) => innerResult.name),
1480
+ ].map((name) => `${name}.tla`);
1481
+ const isFailed = await proveModule(
1482
+ result,
1483
+ `${directory}/${result.name}.thy`,
1484
+ fingerprintsPath,
1485
+ sources,
1486
+ settings,
1487
+ );
1488
+ if (!isFailed) continue;
1489
+ if (parsed.has("--strict")) statuses.push(STRICT_EXIT_STATUS.failed);
1490
+ else if (!isToolbox) {
1491
+ console.error(UNPROVED_ENDING);
1492
+ return TLAPM_FAILURE_STATUS;
1493
+ }
1494
+ }
1495
+ return (
1496
+ Object.values(STRICT_EXIT_STATUS).find((status) => statuses.includes(status)) ??
1497
+ EXIT_STATUS.success
1498
+ );
1257
1499
  };
1258
1500
 
1259
1501
  const checkSpecs = async (args: string[], java: JavaProperties) => {
@@ -1577,7 +1819,8 @@ const runJavaClass = (launch: JavaLaunch) => {
1577
1819
  };
1578
1820
 
1579
1821
  const run = async (args: string[]) => {
1580
- if (args[0] === "prove") return reportErrors(() => runProve(args.slice(1)));
1822
+ if (args[0] === "prove") return reportErrors(() => proveModules(args.slice(1)));
1823
+ if (args[0] === "tlapm") return reportErrors(() => runTlapm(args.slice(1)));
1581
1824
  const launch = getJavaLaunch(args);
1582
1825
  if (launch === undefined) return checkSpecs(args, { libraries: [] });
1583
1826
  // The TLC that -Dtla-ts.tlc names, or else the one of the jar on the class path.
@@ -0,0 +1,250 @@
1
+ // tlapm's fingerprints file, ported from src/backend/fpfile.ml: a Marshal'd FP13 table from each
2
+ // obligation's fingerprint to the result each prover last concluded, which tla-ts and tlapm share.
3
+
4
+ import {
5
+ cpSync,
6
+ existsSync,
7
+ mkdirSync,
8
+ readdirSync,
9
+ readFileSync,
10
+ renameSync,
11
+ rmSync,
12
+ statSync,
13
+ writeFileSync,
14
+ } from "node:fs";
15
+ import { basename, join } from "node:path";
16
+ import { version } from "../package.json";
17
+ import { TlaProofError } from "./errors";
18
+ import { block, isBlock, readMarshaled, writeMarshaled, type OcamlValue } from "./ocaml-marshal";
19
+ import type { ProofAttempt } from "./prove/prove";
20
+
21
+ // Each fingerprint's record of results: one optional result per prover, in V13.str's order.
22
+ export type FingerprintTable = Map<string, OcamlValue[]>;
23
+
24
+ const MAGIC_NUMBER = 20210223;
25
+
26
+ const RECORD_SIZE = 23;
27
+
28
+ // The record's field and the V13.meth constructor of each of tla-ts's provers.
29
+ const PROVERS: Record<string, { field: number; tag: number }> = {
30
+ zenon: { field: 1, tag: 1 },
31
+ isabelle: { field: 2, tag: 0 },
32
+ smt: { field: 10, tag: 8 },
33
+ z3: { field: 11, tag: 9 },
34
+ ls4: { field: 17, tag: 16 },
35
+ };
36
+
37
+ const FAIL_METHOD = 5;
38
+
39
+ const REASONS = ["false", "timeout"];
40
+
41
+ // tlapm stores its own version and those of Zenon and Isabelle with each result, and --safefp
42
+ // trusts a Zenon or Isabelle result only from the same versions. tla-ts's provers are its own.
43
+ const VERSION = `tla-ts ${version}`;
44
+
45
+ // The index in a result of the version --safefp checks, by the record's field.
46
+ const CHECKED_VERSIONS = new Map([
47
+ [PROVERS.zenon.field, 3],
48
+ [PROVERS.isabelle.field, 4],
49
+ ]);
50
+
51
+ const HISTORY_SIZE = 10;
52
+
53
+ const getField = (value: OcamlValue | undefined, index: number) =>
54
+ value !== undefined && isBlock(value) ? value.fields[index] : undefined;
55
+
56
+ const getFloat = (value: OcamlValue | undefined) =>
57
+ value !== undefined && typeof value === "object" && "float" in value ? value.float : Infinity;
58
+
59
+ // Hashtbl.hash on a string with the seed 0: caml_hash's MurmurHash3 mixing of the bytes.
60
+ const hashKey = (key: string) => {
61
+ const bytes = new TextEncoder().encode(key);
62
+ const rotate = (value: number, shift: number) => (value << shift) | (value >>> (32 - shift));
63
+ const mixed = Array.from(
64
+ { length: Math.ceil(bytes.length / 4) },
65
+ (_, index) =>
66
+ bytes[index * 4] |
67
+ (bytes[index * 4 + 1] << 8) |
68
+ (bytes[index * 4 + 2] << 16) |
69
+ (bytes[index * 4 + 3] << 24),
70
+ ).reduce((hash, word) => {
71
+ const data = Math.imul(rotate(Math.imul(word, 0xcc9e2d51), 15), 0x1b873593);
72
+ return (Math.imul(rotate(hash ^ data, 13), 5) + 0xe6546b64) | 0;
73
+ }, 0);
74
+ const first = Math.imul(mixed ^ bytes.length ^ ((mixed ^ bytes.length) >>> 16), 0x85ebca6b);
75
+ const second = Math.imul(first ^ (first >>> 13), 0xc2b2ae35);
76
+ return (second ^ (second >>> 16)) & 0x3fffffff;
77
+ };
78
+
79
+ // The stored result each loaded result came from, which keeps its date and versions, and the
80
+ // record each loaded fingerprint's results came from, which keeps its other provers' results.
81
+ const storedResults = new WeakMap<ProofAttempt, OcamlValue>();
82
+ const storedRecords = new WeakMap<Map<string, ProofAttempt>, OcamlValue[]>();
83
+
84
+ const readBucket = (entry: OcamlValue | undefined): [OcamlValue, OcamlValue][] =>
85
+ entry !== undefined && isBlock(entry)
86
+ ? [[entry.fields[0], entry.fields[1]], ...readBucket(entry.fields[2])]
87
+ : [];
88
+
89
+ // Fpfile.load_fingerprints: replaces the table with the file's. Each bucket lists the latest
90
+ // fingerprint first.
91
+ export const loadFingerprints = (table: FingerprintTable, path: string, isSafe: boolean) => {
92
+ const bytes = readFileSync(path);
93
+ const magic = readMarshaled(bytes, 0);
94
+ const fp = readMarshaled(bytes, magic.next).value;
95
+ if (magic.value !== MAGIC_NUMBER || !isBlock(fp) || fp.tag !== 0)
96
+ throw new TlaProofError("corrupted fingerprint file");
97
+ const buckets = getField(getField(fp, 0), 1);
98
+ const isTrusted = (sti: OcamlValue, field: number) => {
99
+ const index = CHECKED_VERSIONS.get(field);
100
+ return !isSafe || index === undefined || getField(getField(sti, 0), index) === VERSION;
101
+ };
102
+ table.clear();
103
+ (buckets !== undefined && isBlock(buckets) ? buckets.fields : [])
104
+ .flatMap((bucket) => readBucket(bucket).toReversed())
105
+ .forEach(([key, record]) => {
106
+ if (typeof key !== "string" || !isBlock(record))
107
+ throw new TlaProofError("corrupted fingerprint file");
108
+ table.set(
109
+ key,
110
+ record.fields.map((sti, field) => (isTrusted(sti, field) ? sti : 0)),
111
+ );
112
+ });
113
+ };
114
+
115
+ const decodeResult = (prover: string, sti: OcamlValue | undefined): ProofAttempt | undefined => {
116
+ const status = getField(sti, 0);
117
+ const outcome = getField(status, 0);
118
+ const argument = getField(getField(status, 1), 0);
119
+ if (outcome === undefined || outcome === 1) return undefined;
120
+ const seconds = getFloat(getField(prover === "isabelle" ? getField(argument, 0) : argument, 0));
121
+ const tactic = prover === "isabelle" ? getField(argument, 1) : undefined;
122
+ const reason = getField(getField(outcome, 0), 0);
123
+ return {
124
+ method: {
125
+ prover,
126
+ timeLimitMs: seconds * 1000,
127
+ ...(typeof tactic === "string" && { tactic }),
128
+ },
129
+ isProved: outcome === 0,
130
+ isReused: false,
131
+ ...(reason !== undefined && {
132
+ reason: typeof reason === "number" ? REASONS[reason] : String(getField(reason, 0)),
133
+ }),
134
+ };
135
+ };
136
+
137
+ // Fpfile.query: what each of tla-ts's provers concluded for each fingerprint.
138
+ export const getKnownResults = (table: FingerprintTable) =>
139
+ new Map(
140
+ [...table].map(([fingerprint, record]) => {
141
+ const results = new Map(
142
+ Object.entries(PROVERS).flatMap(([prover, known]) => {
143
+ const result = decodeResult(prover, getField(record[known.field], 0));
144
+ if (!result) return [];
145
+ storedResults.set(result, record[known.field]);
146
+ return [[prover, result]];
147
+ }),
148
+ );
149
+ storedRecords.set(results, record);
150
+ return [fingerprint, results];
151
+ }),
152
+ );
153
+
154
+ // Fpfile.fp_writes: a result with the local date, in tlapm's month-1 form, and the versions.
155
+ const encodeResult = (attempt: ProofAttempt) => {
156
+ const now = new Date();
157
+ const method = attempt.method;
158
+ const timeout = { float: method.rlimit ?? method.timeLimitMs / 1000 };
159
+ const argument =
160
+ method.prover === "zenon"
161
+ ? block(0, timeout, FAIL_METHOD)
162
+ : method.prover === "isabelle"
163
+ ? block(0, block(0, timeout), method.tactic ?? "auto")
164
+ : block(0, timeout);
165
+ const reasonIndex = REASONS.indexOf(attempt.reason ?? "");
166
+ const reason =
167
+ attempt.reason === undefined
168
+ ? 0
169
+ : block(0, reasonIndex === -1 ? block(0, attempt.reason) : reasonIndex);
170
+ return block(
171
+ 0,
172
+ block(
173
+ 0,
174
+ block(
175
+ 0,
176
+ attempt.isProved ? 0 : block(0, reason),
177
+ block(PROVERS[method.prover].tag, argument),
178
+ ),
179
+ block(
180
+ 0,
181
+ now.getFullYear(),
182
+ now.getMonth(),
183
+ now.getDate(),
184
+ now.getHours(),
185
+ now.getMinutes(),
186
+ now.getSeconds(),
187
+ ),
188
+ VERSION,
189
+ VERSION,
190
+ VERSION,
191
+ ),
192
+ );
193
+ };
194
+
195
+ // Fpfile.fp_writes and add_to_table: the table of what the run concluded. A fingerprint loaded
196
+ // from the file keeps what other provers concluded, unless --nofp removed it.
197
+ export const updateFingerprints = (
198
+ table: FingerprintTable,
199
+ results: Map<string, Map<string, ProofAttempt>>,
200
+ ) => {
201
+ table.clear();
202
+ results.forEach((attempts, fingerprint) => {
203
+ const record = [...(storedRecords.get(attempts) ?? Array<OcamlValue>(RECORD_SIZE).fill(0))];
204
+ attempts.forEach((attempt, prover) => {
205
+ record[PROVERS[prover].field] = storedResults.get(attempt) ?? encodeResult(attempt);
206
+ });
207
+ table.set(fingerprint, record);
208
+ });
209
+ };
210
+
211
+ const encodeTable = (table: FingerprintTable) => {
212
+ const length = 2 ** Math.max(9, Math.ceil(Math.log2(table.size / 2)));
213
+ const buckets: OcamlValue[] = Array.from({ length }, () => 0);
214
+ table.forEach((record, fingerprint) => {
215
+ const index = hashKey(fingerprint) & (length - 1);
216
+ buckets[index] = block(0, fingerprint, block(0, ...record), buckets[index]);
217
+ });
218
+ return block(0, block(0, table.size, block(0, ...buckets), 0, 512));
219
+ };
220
+
221
+ const pad = (value: number) => String(value).padStart(2, "0");
222
+
223
+ // Fpfile.fp_init: copies the fingerprints file and the modules' sources in the current directory
224
+ // into a dated directory of its history, keeping the 10 latest.
225
+ export const saveHistory = (path: string, sources: string[]) => {
226
+ const now = new Date();
227
+ const history = `${path}.history`;
228
+ const directory = join(
229
+ history,
230
+ `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}_${pad(now.getHours())}_${pad(now.getMinutes())}_${pad(now.getSeconds())}`,
231
+ );
232
+ mkdirSync(directory, { recursive: true });
233
+ [path, ...sources]
234
+ .filter((file) => existsSync(file))
235
+ .forEach((file) => cpSync(file, join(directory, basename(file)), { preserveTimestamps: true }));
236
+ readdirSync(history)
237
+ .map((name) => join(history, name))
238
+ .sort((left, right) => statSync(right).mtimeMs - statSync(left).mtimeMs)
239
+ .slice(HISTORY_SIZE)
240
+ .forEach((old) => rmSync(old, { recursive: true, force: true }));
241
+ };
242
+
243
+ // Fpfile.fp_close_and_consolidate: writes the table beside the file, then over it.
244
+ export const saveFingerprints = (table: FingerprintTable, path: string) => {
245
+ writeFileSync(
246
+ `${path}.tmp`,
247
+ Buffer.concat([writeMarshaled(MAGIC_NUMBER), writeMarshaled(encodeTable(table))]),
248
+ );
249
+ renameSync(`${path}.tmp`, path);
250
+ };