@justjoshn/pi-pstack 0.0.0-stage → 0.15.36-pi.1

package/skills/statechart/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: statechart
+description: "Check a TLA+ model of a system that moves between states, such as a product flow, a protocol, or a service, and draw it as a Mermaid statechart. The report gives the shortest path to each state that breaks a rule. Use for /statechart, or to show a bug as a path through states."
+disable-model-invocation: true
+---
+
+# Statechart
+
+The chart shows how a system moves between states, in the words of the person who reads it. That person, the reader, decides whether the behavior is right.
+
+## Run
+
+Work in a scratch folder outside the repo. Write a TLA+ spec and its config. Then run:
+
+```sh
+<skill dir>/scripts/statechart SPEC.tla [--config FILE] [--view FILE] [--out DIR]
+```
+
+`scripts/statechart.ts` is TypeScript, so run it with a runtime that can execute TypeScript.
+
+The first run installs TLC and Java with mise and needs the network.
+
+## Write the spec
+
+- Write each rule that the reader agrees to as an INVARIANT. A rule can be about a screen, a result, a stored value, or a message. If the model has no variable for a rule, add the variable. Never weaken a rule to make it hold.
+- Write `Next` as a disjunction of the actions, such as `YouPressPlay \/ YouPressStop`. If you do not, TLC names every step `Next`.
+- A state with no step out breaks `NoDeadlock`, also when it is a correct end state. When an INVARIANT or a PROPERTY already has that name, the rule is `CHECK_DEADLOCK`. Add to `Next` an action that is true only in the end states and changes nothing, such as `Done == phase \in {"paid", "failed"} /\ UNCHANGED vars`, and give it a label in `step()`.
+
+## Pick the chart
+
+You do the work that needs judgment: the words on each state and arrow, the phases and their colors, the title, and the report to the reader. Put your work in a view module, and give it with `--view`.
+
+To show the reader's words, the view exports `state(vars)`. The value that `state()` returns picks the form:
+
+- A string gives a flat chart: `export const state = (v) => (v.paid ? "Paid" : "Paying");`
+- An array gives parent states: `export const state = (v) => v.main.split(".");`
+- An object gives one parallel region for each key: `export const state = (v) => ({ Playback: v.playback, Volume: v.volume });`
+
+Label each state with what the reader can see or cares about, such as "Paying" or "Lease held, write pending". Keep variable names out of labels. In `vars`, a TLA+ sequence is an object with keys from 1, so `v.pc[1]` is `pc[1]`. A set is an array.
+
+The view can also export `step(action, from, to)`. It gets the TLC action name and the values before and after the step, and it returns the label of the arrow. Write each step label as the user sees it happen, such as "you press play" or "the connect fails". Do not name the code or the TLA+ action. Two actions that end the same in the chart get the same label, so that they share one arrow.
+
+When a step can occur only in some conditions, end its label with the condition in brackets, in the reader's words, such as `you press play [while the file loads]`. In a regions chart, the command writes the condition on the other regions on the arrow, in the words of their labels, such as `[when Offline]`. Your brackets replace it, and two arrows from one state can then look the same. So in a regions chart, do not write brackets for a condition on another region. When a value that no label shows decides where a step goes, name the result in the label, such as "the roster read fails".
+
+The view can also export these:
+
+- `group(vars)` returns the name of a phase. Each chart state gets the color of its group. When the model states behind one chart state are in different groups, that state gets no color.
+- `colors` gives each group name a color class.
+- `title` is a string that the chart shows at the top.
+
+The command calls `state()` and `group()` at most once for each model state, and `step()` at most once for each step. The chart and the report both use those answers. So make each function depend only on its arguments.
+
+The chart does not draw a step that stays in one label. Split a label when the reader must see such a step.
+
+Aim for about 20 arrows or fewer, because a busier chart is hard to read. First return coarser labels from `state()`. Give one label to values that act the same, and leave out a detail that the reader does not need, such as a call in flight whose return changes nothing. Keep each state of a bug path, and keep each mark. When a merge changes a `breaks` state to `mayBreak`, it hides where a rule breaks. Do not merge two states that break different rules, because the reader then cannot see which rule breaks where. If the chart is still too busy, return `null` from `step()` for the steps that the reader does not need, such as a reset that every state has, or a step whose arrow repeats what other arrows show. Obey these rules when you hide steps:
+
+- Keep each chart state reachable by arrows from a start state.
+- Keep at least one arrow out of each chart state that has a step out in the model.
+- Hide all the steps of an arrow, or none of them. When you hide only some, its condition gets narrower.
+- In the hand-off, say which steps the chart hides.
+
+## Read the report
+
+- In the chart, a state that breaks a rule has the class `breaks`. When only some model states behind it break the rule, it has the class `mayBreak`. The Legend names the rules of each mark. When two rules break, it names both on one mark, so say in the hand-off which state breaks which rule. In a regions chart, a state gets a mark when each combination of region states that includes it can break a rule. When a combination can break a rule and none of its states has a mark, each state in that combination gets a mark.
+- TLC goes past a state that breaks a rule, so the chart shows the states after a bug.
+- Because TLC goes past bugs, a model with no limit on its states can run without end. Keep the constants small, or add a CONSTRAINT.
+- With a VIEW or a SYMMETRY, TLC counts states that it treats as the same as one state, and the chart draws that one state. An arrow can lead to it rather than to the state that the step reaches, and the report says so.
+- TLC checks the rules in each state past a CONSTRAINT or an ACTION_CONSTRAINT, but it does not explore that state or check it for deadlock. When TLC's shortest path for a rule ends in such a state, the chart draws that state, and the report gives that path. The chart does not draw the other states past the bound. A deadlock in such a state does not show. TLC also checks the rules after each step that an ACTION_CONSTRAINT excludes, also when it reaches the next state another way. When TLC's shortest path for a rule ends with such a step, the chart draws that step.
+- The command checks the rules with TLC on the config as written, with one worker. When a rule breaks, the command removes that rule and runs TLC again, until no rule breaks. After the first break, each run stops at 100,000 distinct states, so that a large model does not run without end. When a run reaches that bound or stops on an error, the report lists the rules that it did not check under "Rules not checked", and the chart does not mark them. A rule that is not checked can hold or break. To check it, remove the rules that break from the config, or make the model smaller. The bound adds a module that changes TLC's order of the variables, so for a property TLC can find a different counterexample than a run without the bound.
+- `tlc.out` is what TLC printed on the config as written. When the chart does not show the bug path of a rule that breaks, `tlc-RULE.out` is what TLC printed for the run that found it. When TLC repeats its first warning, plain TLC prints it twice, but `tlc.out` shows it once, because TLC leaves the second copy out of the output that this command reads. That happens only when Java runs with `-XX:+UseParallelGC`, since otherwise TLC's first warning is its advice to pass that flag, which it prints once.
+
+## Show the chart
+
+Show `chart.mmd` to the user as a `mermaid` code block. The chart has a budget of 500 states, counted by TLC on the config as written. Above that, the chart draws only the paths to the rules that break, and when no rule breaks, the command writes no `chart.mmd`. It still checks each rule, and the report gives the state count and each bug path. To see the whole graph, make the model smaller.
+
+Render charts with Pele. When the user asks for an image, or a chart is too large to read as text, follow `references/render.md`. Do not use a different renderer unless the user asks for it.
+
+## Hand off
+
+Give each chart and its Mermaid text to the person who must decide. Add one line for each bug: the rule, the reader's sentence for that rule, and the path as the report numbers it. Say what the model leaves out. Give the command that makes the files again, with a new `--out` folder.
+
+When the model describes code, replay each bug path against the real code, as a test or a live repro, one step for each action. If a bug does not occur, think that the model is wrong until you show that it is not.

package/skills/statechart/references/render.md

@@ -0,0 +1,93 @@
+# Render a chart
+
+Render each `.mmd` file that you show with the npm package `pele@1.9.0`, and give the user the SVG. Install Pele once, outside the repo. Write each SVG next to its `.mmd` file, with the same name. The API is at https://pele.run/api. Pass `{ limit: 1_000_000, outputLimit: 8_000_000, maxEdges: 10_000 }` as the options of `render`. Pele's defaults are smaller than a chart of 500 states can be. When Pele throws a `PeleError`, show the user the Mermaid text and the error.
+
+## Colors
+
+Pele ignores Mermaid `theme` and `themeVariables`. Set its `--pele-*` CSS variables on `.pele`. https://pele.run/theming lists them. The command gives each state the color class of its group, such as `class sN teal`. It marks each bad state with `class sN breaks` or `class sN mayBreak`, each state on the shortest path to a bug with `class sN bugPath`, and each state that a PROPERTY counterexample repeats forever with `class sN repeats`. Pele puts these classes on the state's node. Color the classes with CSS.
+
+The `.mmd` file has a `classDef` line for `breaks` and for `mayBreak`, so that any Mermaid viewer shows the bug marks. It has no `classDef` for the group colors, `bugPath`, or `repeats`. Pele writes each `classDef` color as a `style` attribute on the node, and a `style` attribute wins over a normal CSS rule. So the rules for the marks below use `!important`. Without it, a dark theme keeps the light mark colors. A bug mark sets the fill and the text, and `bugPath` and `repeats` set the border. Put the mark rules after the group colors, so that a mark shows over the group color.
+
+These colors are suggestions. They are the colors of the old skill. Put them in a `<style>` element at the start of each SVG. Each SVG then follows the light or dark setting of the viewer.
+
+```css
+.pele {
+  --pele-bg: #ffffff;
+  --pele-fg: #1c1c1c;
+  --pele-muted: #656565;
+  --pele-line: #808080;
+  --pele-surface: #fcfcfc;
+  --pele-surface-alt: #f1f1f1;
+  --pele-border: #c9c9c9;
+}
+.pele .blue rect { fill: #c3e0ff; }
+.pele .orange rect { fill: #f0d3bf; }
+.pele .purple rect { fill: #e3d5ff; }
+.pele .yellow rect { fill: #f0dcbf; }
+.pele .teal rect { fill: #bfe3df; }
+.pele .tan rect { fill: #e5d9ce; }
+.pele .pink rect { fill: #ffcbe6; }
+.pele .breaks rect {
+  fill: #ffecee !important;
+  stroke: #e72e3b !important;
+  stroke-width: 2.5px !important;
+}
+.pele .breaks text {
+  fill: #cd2834 !important;
+}
+.pele .mayBreak rect {
+  fill: #fff3e6 !important;
+  stroke: #e8730c !important;
+  stroke-width: 2.5px !important;
+}
+.pele .mayBreak text {
+  fill: #b85a06 !important;
+}
+.pele .bugPath rect {
+  stroke: #1680f3 !important;
+  stroke-width: 2.5px !important;
+}
+.pele .repeats rect {
+  stroke: #9b35d6 !important;
+  stroke-width: 2.5px !important;
+  stroke-dasharray: 6 3;
+}
+@media (prefers-color-scheme: dark) {
+  .pele {
+    --pele-bg: #1f1f1f;
+    --pele-fg: #f5f5f5;
+    --pele-muted: #acacac;
+    --pele-line: #939393;
+    --pele-surface: #121212;
+    --pele-surface-alt: #2c2c2c;
+    --pele-border: #4e4e4e;
+  }
+  .pele .blue rect { fill: #1b3857; }
+  .pele .orange rect { fill: #573117; }
+  .pele .purple rect { fill: #3c2e57; }
+  .pele .yellow rect { fill: #573d17; }
+  .pele .teal rect { fill: #174641; }
+  .pele .tan rect { fill: #3d3127; }
+  .pele .pink rect { fill: #57233e; }
+  .pele .breaks rect {
+    fill: #2e2021 !important;
+    stroke: #cf2b35 !important;
+  }
+  .pele .breaks text {
+    fill: #ff6463 !important;
+  }
+  .pele .mayBreak rect {
+    fill: #2e2619 !important;
+    stroke: #d0700f !important;
+  }
+  .pele .mayBreak text {
+    fill: #ffa257 !important;
+  }
+  .pele .bugPath rect {
+    stroke: #116dd2 !important;
+  }
+  .pele .repeats rect {
+    stroke: #9a3fcf !important;
+  }
+}
+```

package/skills/statechart/scripts/backends/cfg.ts

@@ -0,0 +1,33 @@
+import { CHART_STATES, type ConfigSection, RERUN_STATES, type Spec } from "../ir.ts";
+
+export function configText(sections: ConfigSection[], extra: string[]) {
+  const lines: string[] = [];
+  for (const s of sections) lines.push(`${s.key} ${s.tokens.join(" ")}`);
+  lines.push(...extra);
+  return lines.join("\n");
+}
+
+export const boundRun = (module: string) =>
+  [
+    `---- MODULE ChartBound ----`,
+    `EXTENDS ${module}`,
+    `ChartTLC == INSTANCE TLC`,
+    `ChartNaturals == INSTANCE Naturals`,
+    `ChartBound == ChartNaturals!<(ChartTLC!TLCGet("distinct"), ${RERUN_STATES})`,
+    `====`,
+  ].join("\n");
+
+export function chartRun({ module, variables, invariants }: Spec, tag: string) {
+  const every: string[] = [];
+  for (const name of invariants) every.push(`(IF ~${name} THEN {"${name}"} ELSE {}) \\cup `);
+  return [
+    `---- MODULE ChartRun ----`,
+    `EXTENDS ${module}`,
+    `ChartTLC == INSTANCE TLC`,
+    `ChartNaturals == INSTANCE Naturals`,
+    `ChartBudget == ChartNaturals!<=(ChartTLC!TLCGet("distinct"), ${CHART_STATES})`,
+    `ChartBroken == ${every.join("")}{}`,
+    `ChartMark == ChartBroken = {} \\/ ChartTLC!PrintT(<<"${tag}", <<${variables.join(", ")}>>, ChartBroken>>)`,
+    `====`,
+  ].join("\n");
+}

package/skills/statechart/scripts/backends/mermaid.ts

@@ -0,0 +1,201 @@
+import { append, byText, type Chart, type ChartState, type Region, tupleKey } from "../ir.ts";
+
+const BLANK = /\p{White_Space}/u;
+const SAFE = /^[\p{L}\p{N} !'()+,\-./=?[\]"_|@{}:\\^%<>]$/u;
+const HAZARD =
+  /:(?=:|$|\S*#)|\\(?=n)|%(?=%)|<(?=[\p{L}/!?])|_(?![\p{L}\p{N}])|(?<![\p{L}\p{N}])_/giu;
+const DIRECTION = /(direction)\s+(?=LR|RL|TB|BT)/gi;
+const DOUBLE_BRACKET = /\[(?=\[)/g;
+const C4 = /C4(?=Container|Component|Dynamic|Deployment)/g;
+const UNDRAWN = /[\0\x80-\x9f]/;
+const REWRITTEN = ["fl°", "¶ß"];
+const MARKER = /(?<=marker-end=)"/g;
+const firstOf = new Map<number, number>();
+for (const pair of REWRITTEN) {
+  const [first, second] = [...pair].map((c) => c.codePointAt(0) ?? 0);
+  firstOf.set(second, first);
+}
+const KEPT = 0;
+const BLANKED = 1;
+const DROPPED = 2;
+const CODED = 3;
+const JOINS = 4;
+const kindOf = (n: number) => {
+  const c = String.fromCodePoint(n);
+  const kind =
+    c === " "
+      ? KEPT
+      : BLANK.test(c)
+        ? BLANKED
+        : UNDRAWN.test(c)
+          ? DROPPED
+          : SAFE.test(c)
+            ? KEPT
+            : CODED;
+  return firstOf.has(n) ? kind | JOINS : kind;
+};
+const ASCII = Uint8Array.from({ length: 128 }, (_, n) => kindOf(n));
+const wide = new Map<number, number>();
+const kindAt = (n: number) => {
+  if (n < 128) return ASCII[n];
+  let kind = wide.get(n);
+  if (kind === undefined) wide.set(n, (kind = kindOf(n)));
+  return kind;
+};
+const encode = (s: string, ref: (n: number) => string) => {
+  let out = "";
+  let run = 0;
+  let last = -1;
+  for (let i = 0; i < s.length;) {
+    let n = s.charCodeAt(i);
+    let width = 1;
+    if (n >= 0xd800 && n <= 0xdfff) {
+      const low = s.charCodeAt(i + 1);
+      if (n <= 0xdbff && low >= 0xdc00 && low <= 0xdfff) {
+        n = 0x10000 + ((n - 0xd800) << 10) + (low - 0xdc00);
+        width = 2;
+      } else n = 0xfffd;
+    }
+    let kind = kindAt(n);
+    if (kind === DROPPED) {
+      out += s.slice(run, i);
+      run = i + width;
+    } else {
+      const joined = kind >= JOINS && firstOf.get(n) === last;
+      kind &= ~JOINS;
+      if (joined || kind !== KEPT) {
+        out += s.slice(run, i);
+        if (joined) out += ref(0x2060);
+        if (kind === KEPT) run = i;
+        else {
+          out += kind === BLANKED ? " " : ref(n);
+          run = i + width;
+        }
+      }
+      last = n;
+    }
+    i += width;
+  }
+  return out + s.slice(run);
+};
+const code = (s: string, ref: (n: number) => string) =>
+  encode(s, ref)
+    .replace(MARKER, `${ref(0x2060)}"`)
+    .replace(HAZARD, (c) => ref(c.charCodeAt(0)));
+const esc = (s: string, quoted = false) => {
+  const plain = code(s, (n) => `#${n};`);
+  const out = quoted ? plain.replaceAll('"', "#34;") : plain;
+  if (!out.trim()) return "#32;";
+  const turned = out.replace(DIRECTION, "$1#32;");
+  const opened = turned.includes("[[") ? turned.replace(DOUBLE_BRACKET, "#91;") : turned;
+  return opened.includes("C4") ? opened.replace(C4, "C#52;") : opened;
+};
+
+const or = (names: Iterable<string>) => [...names].sort(byText).join(" or ");
+
+const MARK_STYLES = {
+  breaks: "fill:#ffecee,stroke:#e72e3b,stroke-width:2.5px,color:#cd2834",
+  mayBreak: "fill:#fff3e6,stroke:#e8730c,stroke-width:2.5px,color:#b85a06",
+};
+
+export function mermaidLines(chart: Chart) {
+  let next = 0;
+  const marks: string[] = [];
+  const used = new Set<string>();
+  const rules = { breaks: new Set<string>(), mayBreak: new Set<string>() };
+  const region = (r: Region) => {
+    const out: string[] = [];
+    const topIds = new Map<string, string>();
+    const nestedIds = new Map<string, string>();
+    const id = (path: string[]) => {
+      const top = path.length === 1;
+      const named = top ? topIds : nestedIds;
+      const k = top ? path[0] : tupleKey(path);
+      let s = named.get(k);
+      if (s === undefined) named.set(k, (s = `s${next++}`));
+      return s;
+    };
+    const known = new Map<string[], string>();
+    const idOf = (path: string[]) => {
+      let s = known.get(path);
+      if (s === undefined) known.set(path, (s = id(path)));
+      return s;
+    };
+    const tree = (prefix: string[], indent: string, below: ChartState[]) => {
+      const heads = new Map<string, ChartState[]>();
+      for (const s of below) append(heads, s.path[prefix.length], s);
+      for (const [head, under] of heads) {
+        const path = [...prefix, head];
+        let leaf: ChartState | undefined;
+        const inner: ChartState[] = [];
+        for (const s of under)
+          if (s.path.length > path.length) inner.push(s);
+          else leaf = s;
+        if (inner.length) {
+          out.push(`${indent}state "${esc(head, true)}" as ${id(path)} {`);
+          tree(path, indent + "  ", inner);
+          out.push(`${indent}}`);
+        } else if (leaf) {
+          const sid = idOf(leaf.path);
+          out.push(`${indent}${sid}: ${esc(head)}`);
+          let mark: "breaks" | "mayBreak" | undefined =
+            leaf.breaks.length && !leaf.works ? "mayBreak" : undefined;
+          if (mark) for (const b of leaf.breaks) if (b.always) mark = "breaks";
+          if (mark) for (const b of leaf.breaks) rules[mark].add(b.rule.name);
+          const trail = [leaf.lead && "bugPath", leaf.repeats && "repeats"];
+          const color = leaf.group === undefined ? undefined : chart.colors[String(leaf.group)];
+          for (const cls of [color, mark, ...trail])
+            if (cls) {
+              used.add(cls);
+              marks.push(`  class ${sid} ${cls}`);
+            }
+        }
+      }
+    };
+    tree([], "  ", r.states);
+    for (const s of r.states) if (s.start) out.push(`  [*] --> ${idOf(s.path)}`);
+    for (const s of r.steps)
+      out.push(
+        `  ${idOf(s.from)} --> ${idOf(s.to)}: ${esc(s.label + (s.when ? ` [${s.when}]` : ""))}`,
+      );
+    return out;
+  };
+  let body: string[];
+  if (chart.regions.length > 1) {
+    body = [`  state "At the same time" as all {`];
+    for (const [i, r] of chart.regions.entries()) {
+      if (i) body.push("    --");
+      body.push(`    state "${esc(r.name, true)}" as r${i} {`);
+      for (const line of region(r)) body.push(`    ${line}`);
+      body.push("    }");
+    }
+    body.push("  }");
+  } else body = region(chart.regions[0]);
+  const legend: string[][] = [];
+  for (const entry of [
+    ...Object.entries(chart.colors),
+    [`Breaks ${or(rules.breaks)}`, "breaks"],
+    [`Breaks ${or(rules.mayBreak)} in some cases`, "mayBreak"],
+    [`Path to the ${or(chart.paths)} bug`, "bugPath"],
+    [`Repeats forever, so ${or(chart.loops)} breaks`, "repeats"],
+  ])
+    if (used.has(entry[1])) legend.push(entry);
+  const lines: string[] = [];
+  const title = chart.title && code(chart.title, (n) => `fl°°${n}¶ß`).replaceAll("<", "fl°°60¶ß");
+  if (title) lines.push("---", `title: ${JSON.stringify(title)}`, "---");
+  lines.push("stateDiagram-v2");
+  if (chart.regions.length > 1) lines.push("  direction LR");
+  if (legend.length) {
+    lines.push(`  state "Legend" as legend {`);
+    for (const [i, [text]] of legend.entries()) lines.push(`    lg${i}: ${esc(text)}`);
+    lines.push("  }");
+    for (const [i, [, cls]] of legend.entries()) lines.push(`  class lg${i} ${cls}`);
+  }
+  for (const line of body) lines.push(line);
+  for (const [cls, style] of Object.entries(MARK_STYLES))
+    if (used.has(cls)) lines.push(`  classDef ${cls} ${style}`);
+  for (const line of marks) lines.push(line);
+  return lines;
+}
+
+export const mermaid = (chart: Chart) => mermaidLines(chart).join("\n");

package/skills/statechart/scripts/backends/plain-text.ts

@@ -0,0 +1,72 @@
+import { EC, LEVEL, type Message, PART, type Part } from "../ir.ts";
+
+const PREFIX: { [level: number]: string } = {
+  [LEVEL.ERROR]: "Error: ",
+  [LEVEL.TLCBUG]: "TLC Bug: ",
+  [LEVEL.WARNING]: "Warning: ",
+  [LEVEL.STATE]: "State ",
+};
+const MINUTE = 60_000;
+const HOUR = 3_600_000;
+const DAY = 86_400_000;
+
+const pad = (n: number) => String(n).padStart(2, "0");
+
+export function runtime(ms: number) {
+  const t = new Date(ms > DAY ? ms - DAY : ms);
+  const [hh, mm, ss] = [t.getUTCHours(), t.getUTCMinutes(), t.getUTCSeconds()].map(pad);
+  if (ms > DAY)
+    return `${Math.floor((t.getTime() - Date.UTC(t.getUTCFullYear(), 0, 1)) / DAY) + 1}d ${hh}h`;
+  if (ms > HOUR) return `${hh}h ${mm}min`;
+  if (ms > MINUTE) return `${mm}min ${ss}s`;
+  return `${ss}s`;
+}
+
+const firstLine = ({ code, level }: Message, line: string) => {
+  if (code === EC.TLC_BACK_TO_STATE)
+    return line.replace(/^(\d+): Back to state: /, "Back to state $1: ");
+  if (code === EC.TLC_FINISHED)
+    return line.replace(
+      /^Finished in (\d+)ms/,
+      (_, ms: string) => `Finished in ${runtime(Number(ms))}`,
+    );
+  return (PREFIX[level] ?? "") + line;
+};
+
+const render = (m: Message): string =>
+  (m.beforeMarker ?? "") +
+  firstLine(m, m.body.map((part) => (typeof part === "string" ? part : render(part))).join("\n"));
+
+function* printed(parts: Iterable<Part>): Generator<string> {
+  let warned = false;
+  let progress: Message | undefined;
+  for (const part of parts) {
+    if (progress?.body.length && (typeof part === "string" || part.code !== EC.TLC_STATS))
+      yield render(progress);
+    progress = undefined;
+    if (typeof part === "string") {
+      yield part;
+      continue;
+    }
+    if (part.code === EC.TLC_SANY_START || part.code === EC.TLC_SANY_END) continue;
+    if (part.code === EC.TLC_PROGRESS_STATS) progress = part;
+    else if (part.body.length) yield render(part);
+    if (part.level === LEVEL.WARNING && !warned) {
+      yield "(Use the -nowarning option to disable this warning.)";
+      warned = true;
+    }
+  }
+  if (progress?.body.length) yield render(progress);
+}
+
+export function* plainText(parts: Iterable<Part>): Generator<string> {
+  let chunk = "";
+  for (const line of printed(parts)) {
+    chunk += `${line}\n`;
+    if (chunk.length >= PART) {
+      yield chunk;
+      chunk = "";
+    }
+  }
+  if (chunk) yield chunk;
+}

package/skills/statechart/scripts/backends/report.ts

@@ -0,0 +1,177 @@
+import {
+  type Bug,
+  CHART_STATES,
+  type Chart,
+  type Graph,
+  hasSection,
+  list,
+  must,
+  type Property,
+  RERUN_STATES,
+  ruleKey,
+  type Spec,
+  type Stop,
+  type Story,
+  type Verdict,
+} from "../ir.ts";
+
+const stepsOf = (story: Story) => {
+  const path: { step?: string; state: string }[] = [];
+  for (const { step, state } of story) {
+    const parts: string[] = [];
+    for (const [name, names] of Object.entries(state))
+      parts.push((name ? `${name} ` : "") + names.join(" / "));
+    path.push({ step, state: parts.join(", ") });
+  }
+  return path;
+};
+
+const forever = (loop: { state: string }[], stutters: boolean | undefined) => {
+  const quoted = new Set<string>();
+  for (const p of loop) quoted.add(`"${p.state}"`);
+  const runs = [...quoted];
+  if (stutters) return `The run stops in ${runs[0]} forever.`;
+  return runs.length === 1
+    ? `The run stays in ${runs[0]} forever.`
+    : `The run loops through ${list(runs)} forever.`;
+};
+
+const fenced = (text: string) => ["```", text, "```"].join("\n");
+
+export function report(
+  {
+    spec,
+    graph,
+    paths,
+    rules,
+    properties,
+    stop,
+    drawing,
+    states,
+  }: {
+    spec: Spec;
+    graph: Graph;
+    paths: Bug[] | undefined;
+    rules: Verdict[];
+    properties: Property[];
+    stop: Stop | undefined;
+    drawing: { status: number | null } | undefined;
+    states: { distinct: number; initial: number; complete: boolean; cut: boolean };
+  },
+  found: Bug[],
+  chart: Chart | undefined,
+  stories: Map<Bug, Story>,
+) {
+  let size = 0;
+  let arrows = 0;
+  for (const r of chart?.regions ?? []) {
+    size += r.states.length;
+    arrows += r.steps.length;
+  }
+  let past = 0;
+  let pastSteps = 0;
+  let excluded = 0;
+  for (const s of graph.states.values()) {
+    if (s.excluded) excluded++;
+    else if (s.past) past++;
+  }
+  for (const t of graph.steps) if (must(graph.states, t.to).past) pastSteps++;
+  const includes = (n: number) =>
+    chart ? `, and the chart includes ${n === 1 ? "it" : "them"}` : "";
+  const out = [
+    `# ${spec.module}`,
+    "",
+    paths
+      ? `TLC reached ${states.complete && !states.cut && states.distinct > CHART_STATES ? `${states.distinct.toLocaleString("en-US")} states, more than` : "more states than"} the chart budget of ${CHART_STATES}, so ${chart ? `the chart draws only the bug paths: ${size} states and ${arrows} arrows` : "the command wrote no chart.mmd"}.`
+      : `TLC reached ${graph.states.size - past - excluded} states and ${graph.steps.length - pastSteps} steps. The chart draws ${size} states and ${arrows} arrows.`,
+  ];
+  if (drawing)
+    out.push(
+      `TLC stopped the drawing run with exit ${drawing.status}, so the chart draws only the states that it reached before it stopped.`,
+    );
+  if (!paths && !drawing && graph.states.size === past + excluded)
+    out.push(
+      states.initial
+        ? "Every initial state is outside the constraints, so TLC explores none of them."
+        : "TLC found no state that satisfies Init, so no state can break a rule.",
+    );
+  if (past)
+    out.push(
+      `${past === 1 ? "1 state outside the constraints ends" : `${past} states outside the constraints each end`} a rule's path${includes(past)}. TLC checks the rules in a state outside the constraints, but it does not explore past it.`,
+    );
+  if (excluded)
+    out.push(
+      `${excluded === 1 ? "1 step that the constraints exclude ends" : `${excluded} steps that the constraints exclude each end`} a rule's path${includes(excluded)}. TLC checks the rules after such a step, but it does not take the step.`,
+    );
+  if (chart?.inside)
+    out.push(`The chart does not draw ${chart.inside} steps that stay in one chart state.`);
+  if (chart?.quiet)
+    out.push(`The view hides ${chart.quiet} steps, so the chart does not draw them.`);
+  for (const { rule, outcome } of rules)
+    if (
+      !paths &&
+      rule.kind === "deadlock" &&
+      outcome === "broken" &&
+      (drawing || hasSection(spec, "CONSTRAINT", "ACTION_CONSTRAINT"))
+    )
+      out.push(
+        drawing
+          ? "The chart marks only the deadlock that TLC reports, because the drawing run stopped before it reached every state."
+          : "The chart marks only the deadlock that TLC reports. Under a CONSTRAINT or an ACTION_CONSTRAINT, a state with no step in the chart can still have steps that the constraints leave out, and TLC does not count it as a deadlock.",
+      );
+  if (chart?.lie) out.push(`${chart.lie} So the chart draws parent states in place of regions.`);
+  out.push(...(chart?.notes ?? []));
+  const merged: string[] = [];
+  for (const k of ["VIEW", "SYMMETRY"]) if (hasSection(spec, k)) merged.push(k);
+  if (chart && merged.length)
+    out.push(
+      `With ${list(merged)}, TLC keeps one representative for each group of states that it counts as the same. An arrow can lead to the representative rather than to the state that the step reaches.`,
+    );
+  for (const bug of found) {
+    const steps = `${bug.path.length} step${bug.path.length === 1 ? "" : "s"}`;
+    out.push("", `## ${bug.rule.name} breaks`);
+    out.push(
+      bug.rule.kind === "property"
+        ? `TLC's counterexample is in tlc-${bug.rule.name}.out. It has ${steps}:`
+        : `The shortest path has ${steps}:`,
+    );
+    const path = stepsOf(must(stories, bug));
+    for (const [i, p] of path.entries()) out.push(`${i}. ${p.step ? `${p.step}: ` : ""}${p.state}`);
+    if (bug.loop !== undefined) out.push(forever(path.slice(bug.loop), bug.stutters));
+  }
+  const drawn = new Set<string>();
+  for (const b of found) drawn.add(ruleKey(b.rule));
+  const holds: string[] = [];
+  const unchecked: string[] = [];
+  for (const { rule, outcome, messages } of [...rules, ...properties]) {
+    if (outcome === "holds") holds.push(rule.name);
+    else if (outcome === "not checked") unchecked.push(rule.name);
+    else if (messages && !drawn.has(ruleKey(rule)))
+      out.push(
+        "",
+        `## ${rule.name} breaks`,
+        `TLC found a counterexample. It is in tlc-${rule.name}.out.`,
+      );
+  }
+  if (holds.length) out.push("", "## Rules that hold", holds.join(", "));
+  if (unchecked.length) out.push("", "## Rules not checked", unchecked.join(", "));
+  if (unchecked.length && states.cut)
+    out.push(
+      `After the first break, each TLC run stops at ${RERUN_STATES.toLocaleString("en-US")} distinct states. A run reached that bound before it checked ${unchecked.length === 1 ? "this rule" : "these rules"} in every state.`,
+    );
+  if (stop)
+    out.push(
+      ...(unchecked.length
+        ? [
+            `TLC stopped with exit ${stop.status} before it checked ${unchecked.length === 1 ? "this rule" : "these rules"}:`,
+          ]
+        : ["", "## TLC stopped", `TLC stopped with exit ${stop.status}:`]),
+      fenced(stop.message),
+    );
+  for (const p of properties)
+    if (p.outcome === "holds" && p.initialOnly)
+      out.push(
+        `TLC checked ${p.rule.name} only in the initial states, because it has no [], <>, or ~>. List it as an INVARIANT to check every state.`,
+      );
+  return out.join("\n");
+}