pi-pstack-native 0.0.0-stage → 1.0.0

package/skills/statechart/scripts/chart-to-tla.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { parseMermaid } from "./lib.mjs";
+
+const USAGE = "Usage: node chart-to-tla.mjs CHART.mmd --module NAME [--dir OUT]";
+
+const args = {};
+for (let i = 2; i < process.argv.length; i++) {
+  const a = process.argv[i];
+  if (a === "--module") args.module = process.argv[++i];
+  else if (a === "--dir") args.dir = process.argv[++i];
+  else if (!a.startsWith("-") && !args.chart) args.chart = a;
+  else {
+    console.error(`unknown argument ${a}.`);
+    process.exit(2);
+  }
+}
+if (!args.chart || !/^[A-Za-z][A-Za-z0-9_]*$/.test(args.module ?? "")) {
+  console.error(USAGE);
+  process.exit(2);
+}
+const dir = args.dir ?? path.dirname(args.chart);
+const { regions, nevers } = parseMermaid(fs.readFileSync(args.chart, "utf8"));
+
+const RESERVED = new Set(["vars", "Init", "Next", "Spec", "TypeOK", "Settled"]);
+const taken = new Set(RESERVED);
+function ident(words, lower) {
+  const parts = words
+    .normalize("NFKD")
+    .replace(/[^A-Za-z0-9]+/g, " ")
+    .trim()
+    .split(" ")
+    .filter(Boolean);
+  let id =
+    parts
+      .map((p, i) => (lower && i === 0 ? p[0].toLowerCase() : p[0].toUpperCase()) + p.slice(1))
+      .join("") || "Step";
+  if (/^[0-9]/.test(id)) id = `${lower ? "r" : "S"}${id}`;
+  let unique = id;
+  for (let n = 2; taken.has(unique); n++) unique = `${id}${n}`;
+  taken.add(unique);
+  return unique;
+}
+const str = (s) => `"${s.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+const set = (xs) => `{${[...xs].map(str).join(", ")}}`;
+
+const vars = Object.entries(regions).map(([name, r]) => {
+  if (r.states.size === 0) throw new Error(`region ${name} has no states`);
+  if (r.initial.size === 0) throw new Error(`region ${name} has no [*] --> start`);
+  return { name, v: ident(name, true), ...r };
+});
+
+function guardOf(g) {
+  if (!g) return null;
+  const parts = Object.entries(g.states).map(([name, states]) => {
+    const { v } = vars.find((x) => x.name === name);
+    return states.length === 1 ? `${v} = ${str(states[0])}` : `${v} \\in ${set(states)}`;
+  });
+  return g.not ? `~(${parts.join(" \\/ ")})` : parts.join(" /\\ ");
+}
+
+const actions = [];
+const byLabel = new Map();
+for (const [ri, r] of vars.entries()) {
+  for (const t of r.transitions) {
+    let a = t.label ? byLabel.get(t.label) : null;
+    if (!a) {
+      a = { label: t.label, moves: new Map() };
+      actions.push(a);
+      if (t.label) byLabel.set(t.label, a);
+    }
+    if (!a.moves.has(ri)) a.moves.set(ri, []);
+    const moves = a.moves.get(ri);
+    const when = guardOf(t.guard);
+    if (!moves.some((m) => m.from === t.from && m.to === t.to && m.when === when))
+      moves.push({ from: t.from, to: t.to, when });
+  }
+}
+for (const a of actions) {
+  const only = a.label ? null : [...a.moves.values()][0][0];
+  a.name = ident(a.label || `${only.from} to ${only.to}`, false);
+}
+
+const out = [];
+const conjuncts = (lines) => lines.map((l) => `    /\\ ${l}`);
+out.push(`---- MODULE ${args.module} ----`);
+out.push(`\\* Generated by chart-to-tla.mjs from ${path.basename(args.chart)}.`);
+out.push("\\* Each region is one variable and each transition label is one action.");
+out.push("\\* Once you add guards and variables from the real code, this file is the source.");
+out.push(
+  `\\* statechart.mjs from-chart ${path.basename(args.chart)} keeps it, checks it, and compares it with the chart.`,
+);
+out.push("");
+out.push(`VARIABLES ${vars.map((x) => x.v).join(", ")}`);
+out.push(`vars == <<${vars.map((x) => x.v).join(", ")}>>`);
+out.push("");
+for (const x of vars)
+  out.push(`\\* Region ${x.name}`, `${x.v}States == ${set([...x.states].sort())}`);
+out.push("");
+out.push("TypeOK ==", ...conjuncts(vars.map((x) => `${x.v} \\in ${x.v}States`)));
+out.push("");
+out.push(
+  "Init ==",
+  ...conjuncts(
+    vars.map((x) =>
+      x.initial.size === 1 ? `${x.v} = ${str([...x.initial][0])}` : `${x.v} \\in ${set(x.initial)}`,
+    ),
+  ),
+);
+const enabled = (v, m) => `${v} = ${str(m.from)}${m.when ? ` /\\ ${m.when}` : ""}`;
+function whetherTakes(a, ri) {
+  const { v } = vars[ri];
+  const moves = a.moves.get(ri);
+  if (moves.every((m) => !m.when)) {
+    const from = set(new Set(moves.map((m) => m.from)));
+    return { can: `${v} \\in ${from}`, cannot: `${v} \\notin ${from}` };
+  }
+  const any = moves.map((m) => `(${enabled(v, m)})`).join(" \\/ ");
+  return { can: any, cannot: `~(${any})` };
+}
+for (const a of actions) {
+  out.push("");
+  if (a.label) out.push(`\\* ${a.label}`);
+  out.push(`${a.name} ==`);
+  const moving = [...a.moves.keys()];
+  const shared = moving.length > 1;
+  if (shared) out.push(`    /\\ (${moving.map((ri) => whetherTakes(a, ri).can).join(" \\/ ")})`);
+  for (const ri of moving) {
+    const { v } = vars[ri];
+    const ds = a.moves.get(ri).map((m) => `(${enabled(v, m)} /\\ ${v}' = ${str(m.to)})`);
+    if (shared) ds.push(`(${whetherTakes(a, ri).cannot} /\\ UNCHANGED ${v})`);
+    out.push(`    /\\ \\/ ${ds[0]}`);
+    for (const d of ds.slice(1)) out.push(`       \\/ ${d}`);
+  }
+  const still = vars.filter((_, ri) => !a.moves.has(ri)).map((x) => x.v);
+  if (still.length) out.push(`    /\\ UNCHANGED <<${still.join(", ")}>>`);
+}
+out.push("");
+out.push(actions.length ? `Next == ${actions.map((a) => a.name).join(" \\/ ")}` : "Next == FALSE");
+out.push("");
+out.push("Spec == Init /\\ [][Next]_vars");
+
+function resolve(item) {
+  const hits = [];
+  for (const [ri, x] of vars.entries()) {
+    const inside = x.states.has(item)
+      ? [item]
+      : [...x.states].filter((s) => s.startsWith(`${item}.`));
+    if (inside.length) hits.push({ ri, inside });
+  }
+  if (hits.length === 0)
+    throw new Error(`never line names "${item}", which is not a state in the chart`);
+  if (hits.length > 1)
+    throw new Error(
+      `never line names "${item}", which is a state in regions ${hits.map((h) => vars[h.ri].name).join(" and ")}; rename one`,
+    );
+  return hits[0];
+}
+const invariants = [];
+for (const n of nevers) {
+  if (taken.has(n.name)) throw new Error(`never name ${n.name} is already used in the spec`);
+  taken.add(n.name);
+  const parts = n.states.map(resolve);
+  const regionsUsed = new Set(parts.map((p) => p.ri));
+  if (regionsUsed.size !== parts.length)
+    throw new Error(
+      `never ${n.name} names two states of one region; one region is in one state at a time`,
+    );
+  const cond = parts.map((p) =>
+    p.inside.length === 1
+      ? `${vars[p.ri].v} = ${str(p.inside[0])}`
+      : `${vars[p.ri].v} \\in ${set(p.inside)}`,
+  );
+  out.push("");
+  if (n.sentence) out.push(`\\* ${n.sentence}`);
+  out.push(`${n.name} == ~(${cond.join(" /\\ ")})`);
+  invariants.push(n.name);
+}
+out.push("", "====", "");
+
+const rules = ["TypeOK", ...invariants];
+const cfg = ["SPECIFICATION Spec", ...rules.map((r) => `INVARIANT ${r}`), ""];
+
+const labels = Object.fromEntries(actions.map((a) => [a.name, a.label]));
+const map = [
+  `// Generated by chart-to-tla.mjs from ${path.basename(args.chart)}. Reader states are the chart's own states.`,
+  `export const regions = ${JSON.stringify(vars.map((x) => x.v))};`,
+  `const LABELS = ${JSON.stringify(labels, null, "\t")};`,
+  "",
+  "// The actions the reader takes. facts.settled needs them. Add cause() and detail() as the spec grows.",
+  "export const readerActions = [];",
+  'export const state = (v) => regions.map((r) => v[r]).join(" | ");',
+  "export const step = (action) => LABELS[action] ?? action;",
+  "",
+];
+
+fs.mkdirSync(dir, { recursive: true });
+fs.writeFileSync(path.join(dir, `${args.module}.tla`), out.join("\n"));
+fs.writeFileSync(path.join(dir, `${args.module}.cfg`), cfg.join("\n"));
+fs.writeFileSync(path.join(dir, `${args.module}.map.mjs`), map.join("\n"));
+console.error(
+  `${args.module}: ${vars.length} region variable(s), ${actions.length} action(s), rules ${rules.join(" ")} -> ${path.join(dir, args.module)}.{tla,cfg,map.mjs}`,
+);

package/skills/statechart/scripts/compare-charts.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import process from "node:process";
+import { FULL_LABELS, LEGEND_ID, NO_LOOPS, compareCharts, parseMermaid } from "./lib.mjs";
+
+const USAGE = "Usage: node compare-charts.mjs EXPECTED.mmd ACTUAL.mmd";
+
+const files = [];
+for (const a of process.argv.slice(2)) {
+  if (a.startsWith("-") || files.length === 2) {
+    console.error(`unknown argument ${a}.`);
+    process.exit(2);
+  } else files.push(a);
+}
+if (files.length < 2) {
+  console.error(USAGE);
+  process.exit(2);
+}
+const [expectedFile, actualFile] = files;
+
+const orExit = (file, f) => {
+  try {
+    return f();
+  } catch (e) {
+    console.error(`${file}: ${e.message}`);
+    process.exit(2);
+  }
+};
+const [expectedText, actualText] = files.map((f) => orExit(f, () => fs.readFileSync(f, "utf8")));
+const has = (re) => re.test(actualText);
+const textRefusals = [
+  [
+    has(/^\s*%% second model/m),
+    "it has a second model; draw ACTUAL without --fixed-dot or --against-dot",
+  ],
+  [
+    has(new RegExp(`^\\s*state\\s+"[^"]*"\\s+as\\s+(?!${LEGEND_ID}\\b)\\w+\\s*\\{`, "m")),
+    "it has boxes; draw ACTUAL with --flat",
+  ],
+  [
+    has(new RegExp(`^\\s*state\\s+"[^"]*"\\s+as\\s+${LEGEND_ID}\\s*\\{`, "m")) &&
+      !actualText.includes(FULL_LABELS),
+    "edge labels write shared words once; draw ACTUAL with --full-labels",
+  ],
+];
+for (const [bad, why] of textRefusals) {
+  if (bad) {
+    console.error(`${actualFile}: ${why}`);
+    process.exit(2);
+  }
+}
+const expectedRegions = orExit(expectedFile, () => parseMermaid(expectedText).regions);
+const actualRegions = orExit(actualFile, () => parseMermaid(actualText).regions);
+const numbered = Object.values(actualRegions)
+  .flatMap((r) => r.transitions)
+  .some((t) => /^\d+(, \d+)*\. /.test(t.label));
+if (numbered) {
+  console.error(
+    `${actualFile}: an edge label is a numbered path step; draw ACTUAL with --highlight 0`,
+  );
+  process.exit(2);
+}
+
+const rows = compareCharts(expectedRegions, actualRegions, {
+  loops: !actualText.includes(NO_LOOPS),
+});
+let differences = 0;
+for (const [title, xs] of rows) {
+  console.log(`${title}:`);
+  for (const x of xs) console.log(`  ${x}`);
+  differences += xs.length;
+}
+console.log(differences === 0 ? "same" : `${differences} difference(s)`);
+process.exit(differences === 0 ? 0 : 1);

package/skills/statechart/scripts/frontends/config.ts

@@ -0,0 +1,276 @@
+import { CHECK_DEADLOCK, type Config } from "../ir.ts";
+
+type ListField = "invariants" | "properties" | "constraints" | "actionConstraints";
+type Section = {
+  key: string;
+  plural?: string;
+  field?:
+    | ListField
+    | "checkDeadlock"
+    | "init"
+    | "next"
+    | "spec"
+    | "view"
+    | "symmetry"
+    | "type"
+    | "typeConstraint";
+  undefinedNoun?: string;
+};
+const isListField = (field: Section["field"]): field is ListField =>
+  field === "invariants" ||
+  field === "properties" ||
+  field === "constraints" ||
+  field === "actionConstraints";
+
+const SECTIONS = new Map<string, Section>();
+for (const section of [
+  { key: "CONSTANT", plural: "CONSTANTS" },
+  { key: CHECK_DEADLOCK, field: "checkDeadlock" },
+  { key: "INIT", field: "init", undefinedNoun: "initial predicate" },
+  { key: "NEXT", field: "next", undefinedNoun: "next state action" },
+  { key: "SPECIFICATION", field: "spec", undefinedNoun: "name" },
+  { key: "VIEW", field: "view", undefinedNoun: "view function" },
+  { key: "SYMMETRY", field: "symmetry", undefinedNoun: "symmetry function" },
+  { key: "TYPE", field: "type" },
+  { key: "TYPE_CONSTRAINT", field: "typeConstraint" },
+  { key: "INVARIANT", plural: "INVARIANTS", field: "invariants", undefinedNoun: "invariant" },
+  { key: "PROPERTY", plural: "PROPERTIES", field: "properties", undefinedNoun: "property" },
+  { key: "CONSTRAINT", plural: "CONSTRAINTS", field: "constraints", undefinedNoun: "constraint" },
+  {
+    key: "ACTION_CONSTRAINT",
+    plural: "ACTION_CONSTRAINTS",
+    field: "actionConstraints",
+    undefinedNoun: "action constraint",
+  },
+] satisfies Section[]) {
+  SECTIONS.set(section.key, section);
+  if (section.plural) SECTIONS.set(section.plural, section);
+}
+export const NAME = /^\w*[A-Za-z]\w*$/;
+const WORD = /\w+/y;
+const CONFIG_HOLDS =
+  "A config can hold only names, numbers, strings, comments, and the symbols { } ( ) [ ] , = ! <-.";
+const shown = (c: string) => {
+  const code = c.codePointAt(0) ?? 0;
+  const hex = `U+${code.toString(16).toUpperCase().padStart(4, "0")}`;
+  if (code < 0x20 || code === 0x7f) return hex;
+  return code < 0x7f ? `"${c}"` : `"${c}" (${hex})`;
+};
+
+type Token = { image: string; line: number };
+
+function tokenizeConfig(text: string, cannot: (line: number, words: string) => Error) {
+  if (text.startsWith("\uFEFF"))
+    throw cannot(1, "The file starts with a byte order mark. Save it as UTF-8 without one.");
+  const tokens: Token[] = [];
+  let line = 1;
+  let last = 1;
+  let i = 0;
+  const skip = (to: number) => {
+    for (; i < to; i++) {
+      last = line;
+      if (text[i] === "\n" || (text[i] === "\r" && text[i + 1] !== "\n")) line++;
+    }
+  };
+  const push = (image: string) => {
+    tokens.push({ image, line });
+    skip(i + image.length);
+  };
+  while (i < text.length) {
+    const c = text[i];
+    const two = text.slice(i, i + 2);
+    const start = line;
+    if (c === " " || c === "\t" || c === "\n" || c === "\r") skip(i + 1);
+    else if (two === "\\*") {
+      const end = text.slice(i).search(/[\n\r]/);
+      skip(end < 0 ? text.length : i + end);
+    } else if (two === "(*") {
+      const marks = /\(\*|\*\)/g;
+      let depth = 0;
+      do {
+        marks.lastIndex = i;
+        const m = marks.exec(text);
+        if (!m) throw cannot(start, "A comment starts here and does not end.");
+        depth += m[0] === "(*" ? 1 : -1;
+        skip(m.index + 2);
+      } while (depth);
+    } else if (c === '"') {
+      let j = i + 1;
+      while (text[j] !== '"') {
+        const ch = text[j];
+        if (ch === undefined) throw cannot(start, "A string starts here and does not end.");
+        if (ch === "\n" || ch === "\r")
+          throw cannot(
+            start,
+            "A string starts here and does not end on its line. Write \\n for a line break in a string.",
+          );
+        if (ch === "\0") throw cannot(start, "A string has the character U+0000.");
+        if (ch === "\\" && text[j + 1] !== undefined && !'"\\ntrf'.includes(text[j + 1]))
+          throw cannot(
+            start,
+            `A string has a backslash before ${shown(text[j + 1])}. A string can use only the escapes \\" \\\\ \\n \\t \\r \\f.`,
+          );
+        j += ch === "\\" ? 2 : 1;
+      }
+      push(text.slice(i, j + 1));
+    } else if (/\w/.test(c)) {
+      WORD.lastIndex = i;
+      const word = WORD.exec(text)?.[0] ?? c;
+      if (/^[WS]F_/.test(word))
+        throw cannot(
+          start,
+          `TLC reads ${word.slice(0, 3)} at the start of a word as a TLA+ keyword, so it cannot read ${word} as a name.`,
+        );
+      if (!/[A-Za-z]/.test(word) && word !== "_") {
+        if (/\D/.test(word))
+          throw cannot(
+            start,
+            `TLC splits ${word} into ${word.match(/\d+|_/g)?.join(" ")}, because a name needs a letter.`,
+          );
+        if (Number(word) > 2147483647)
+          throw cannot(start, `TLC cannot read a number above 2147483647, such as ${word}.`);
+      }
+      push(word);
+    } else if (two === "<-") push(two);
+    else if (["[]", "]_", "==", "=<", "!!"].includes(two))
+      throw cannot(start, `TLC reads ${two} as one TLA+ symbol, and a config cannot hold it.`);
+    else if ("{}()[],=!".includes(c)) push(c);
+    else {
+      const ch = String.fromCodePoint(text.codePointAt(i) ?? 0);
+      const where = ch > "\x7f" ? " outside a string" : "";
+      throw cannot(start, `It cannot read the character ${shown(ch)}${where}. ${CONFIG_HOLDS}`);
+    }
+  }
+  return { tokens, end: last };
+}
+
+export function readConfig({ file, text }: { file: string; text: string }): Config {
+  const refuse = (line: number, words: string) =>
+    new Error(`TLC refuses the config ${file} at line ${line}. ${words}`);
+  const cannot = (line: number, words: string) =>
+    new Error(`The command cannot read the config ${file} at line ${line}. ${words}`);
+  const { tokens, end } = tokenizeConfig(text, cannot);
+  const eof: Token = { image: "", line: end };
+  let at = 0;
+  const next = () => tokens[at++] ?? eof;
+  let deferred: Error | undefined;
+  const defer = (error: Error) => (deferred ??= error);
+  const defined = (t: Token, undefinedNoun: string | undefined) => {
+    if (!NAME.test(t.image))
+      defer(
+        refuse(
+          t.line,
+          `The ${undefinedNoun} ${t.image} specified in the configuration file is not defined in the specification.`,
+        ),
+      );
+  };
+  const name = (t: Token, what: string) => {
+    if (SECTIONS.has(t.image))
+      defer(cannot(t.line, `TLC would read the keyword ${t.image} as ${what}.`));
+    else if (!NAME.test(t.image))
+      defer(cannot(t.line, `TLC would read ${t.image} as ${what}, and it is not a name.`));
+  };
+  const value = (t: Token): void => {
+    if (t === eof) throw refuse(t.line, "It was expecting a value, but did not find it.");
+    if (t.image === "{") {
+      t = next();
+      if (t.image === "}") return;
+      value(t);
+      while ((t = next()).image === ",") value(next());
+      if (t.image !== "}") throw refuse(t.line, "It was expecting }, but did not find it.");
+    } else if (SECTIONS.has(t.image))
+      defer(cannot(t.line, `TLC would read the keyword ${t.image} as a value.`));
+    else if (!NAME.test(t.image) && !/^(\d+|".*")$/.test(t.image))
+      defer(
+        cannot(
+          t.line,
+          `TLC would read ${t.image} as a value. A value is a name, a number, a string, or a set in braces.`,
+        ),
+      );
+  };
+  const constant = (t: Token, loc: number) => {
+    name(t, "a constant name");
+    for (t = next(); t.image === "!"; t = next()) name((t = next()), "a constant name");
+    if (t.image === "<-") {
+      t = next();
+      if (t.image === "[") {
+        t = next();
+        if (t === eof) throw refuse(t.line, "Expected an identifier after <-[.");
+        name(t, "a module name");
+        t = next();
+        if (t.image !== "]") throw refuse(t.line, "It was expecting ], but did not find it.");
+        t = next();
+        if (t === eof) throw refuse(t.line, "Expected an identifier after <-[mod].");
+      } else if (t === eof) throw refuse(t.line, "Expected an identifier after <-.");
+      name(t, "the name after <-");
+      return;
+    }
+    if (t.image === "(") {
+      value(next());
+      while ((t = next()).image === ",") value(next());
+      if (t.image !== ")")
+        throw refuse(
+          loc,
+          "TLC gives no reason here. An operator's arguments are one or more values in ( ), with commas between them.",
+        );
+      t = next();
+    }
+    if (t.image !== "=") throw refuse(t.line, "It was expecting = or <-, but did not find it.");
+    t = next();
+    if (t.image === "[") {
+      t = next();
+      if (t === eof) throw refuse(t.line, "Expected an identifier after =[.");
+      name(t, "a module name");
+      t = next();
+      if (t.image !== "]") throw refuse(t.line, "It was expecting ], but did not find it.");
+      t = next();
+    }
+    value(t);
+  };
+  const config: Config = {
+    sections: [],
+    invariants: [],
+    properties: [],
+    constraints: [],
+    actionConstraints: [],
+  };
+  for (let t = next(); t !== eof;) {
+    const keyword = t;
+    const section = SECTIONS.get(keyword.image);
+    if (!section) throw refuse(t.line, "It was expecting a keyword, but did not find it.");
+    const { key, field, undefinedNoun } = section;
+    const begin = at;
+    if (field === undefined) {
+      for (t = next(); t !== eof && !SECTIONS.has(t.image); t = next()) constant(t, keyword.line);
+    } else if (isListField(field)) {
+      for (t = next(); t !== eof && !SECTIONS.has(t.image); t = next()) {
+        config[field].push(t.image);
+        defined(t, undefinedNoun);
+      }
+    } else {
+      t = next();
+      if (t === eof)
+        throw refuse(
+          keyword.line,
+          `The keyword ${keyword.image} was not followed by an identifier.`,
+        );
+      if (field === "checkDeadlock" && t.image !== "TRUE" && t.image !== "FALSE")
+        throw refuse(t.line, "It was expecting TRUE or FALSE, but did not find it.");
+      if (config[field] !== undefined)
+        throw refuse(keyword.line, `The keyword ${keyword.image} appeared twice.`);
+      if (field === "checkDeadlock") config[field] = t.image === "TRUE";
+      else {
+        config[field] = t.image;
+        if (SECTIONS.has(t.image))
+          defer(cannot(t.line, `TLC would read the keyword ${t.image} as the name after ${key}.`));
+        else if (undefinedNoun) defined(t, undefinedNoun);
+      }
+      t = next();
+    }
+    const images: string[] = [];
+    for (let k = begin; k < (t === eof ? tokens.length : at - 1); k++) images.push(tokens[k].image);
+    config.sections.push({ key, line: keyword.line, tokens: images });
+  }
+  if (deferred) throw deferred;
+  return config;
+}

package/skills/statechart/scripts/frontends/dot.ts

@@ -0,0 +1,74 @@
+import { type Graph, type State, type Step, type Value, type Vars } from "../ir.ts";
+import { parseValue } from "./value.ts";
+
+const unescapeDot = (s: string) => {
+  let i = s.indexOf("\\");
+  if (i === -1) return s;
+  let out = "";
+  let from = 0;
+  for (; i !== -1 && i + 1 < s.length; i = s.indexOf("\\", i)) {
+    const c = s[i + 1];
+    if (c === "\n" || c === "\r" || c === "\u2028" || c === "\u2029") {
+      i++;
+      continue;
+    }
+    out += s.slice(from, i) + (c === "n" ? "\n" : c);
+    i += 2;
+    from = i;
+  }
+  return out + s.slice(from);
+};
+
+export const parseState = (label: string, parsed = new Map<string, [string, Value]>()): Vars => {
+  const pairs: [string, Value][] = [];
+  for (const part of (label.startsWith("/\\ ") ? label.slice(3) : label).split("\n/\\ ")) {
+    let pair = parsed.get(part);
+    if (!pair) {
+      const [, name, value] = /^(\w+)\s*=\s*([\s\S]*)$/.exec(part) ?? [];
+      if (!name) throw new Error(`cannot read the TLC state line "${part}"`);
+      parsed.set(part, (pair = [name, parseValue(value)]));
+    }
+    pairs.push(pair);
+  }
+  return Object.fromEntries(pairs);
+};
+
+export type Lines = string | Iterable<string>;
+
+export const linesOf = (input: Lines) => (typeof input === "string" ? input.split("\n") : input);
+
+export function parseDot(input: Lines): Graph {
+  const states = new Map<string, State>();
+  const steps = new Map<string, Step>();
+  const parsed = new Map<string, [string, Value]>();
+  const owned = new Map<string, string>();
+  const own = (s: string) => {
+    let copy = owned.get(s);
+    if (copy === undefined) owned.set((copy = String(JSON.parse(JSON.stringify(s)))), copy);
+    return copy;
+  };
+  for (const line of linesOf(input)) {
+    const edge = /^(-?\d+) -> (-?\d+) \[label="([^"]*)"/.exec(line);
+    if (edge) {
+      steps.set(edge.slice(1).join(" "), {
+        from: own(edge[1]),
+        to: own(edge[2]),
+        action: own(edge[3]),
+      });
+      continue;
+    }
+    const node = /^(-?\d+) \[label="((?:[^"\\]|\\.)*)"(,style = filled)?/.exec(line);
+    if (node)
+      states.set(own(node[1]), {
+        vars: parseState(unescapeDot(node[2]), parsed),
+        start: !!node[3],
+        breaks: [],
+      });
+  }
+  for (const loose of steps.values())
+    if (!states.has(loose.from) || !states.has(loose.to))
+      throw new Error(
+        `The TLC graph dump has a step ${loose.action} to or from a state that it does not list.`,
+      );
+  return { states, steps: [...steps.values()] };
+}