--- name: statechart description: "检查在状态之间迁移的系统的 TLA+ 模型,例如产品流程、协议或服务,并把它画成 Mermaid statechart。报告给出到达每个打破规则的状态的最短路径。用于 /statechart,或把 bug 显示为一条穿过状态的路径。" disable-model-invocation: true --- # Statechart 这张图用阅读者的话,说明系统怎样从一个状态走到另一个状态。对不对,由阅读者来判断。 ## 运行 在仓库外面的临时目录里工作。先写 TLA+ 规约和配置,再运行: ```sh /scripts/statechart SPEC.tla [--config FILE] [--view FILE] [--out DIR] ``` `scripts/statechart.ts` 是 TypeScript,要用能跑 TypeScript 的运行时来执行。 第一次运行会用 mise 安装 TLC 和 Java,需要联网。 ## 写规约 - 把阅读者同意的每条规则写成 INVARIANT。规则可以关于一个界面、一个结果、一个存下的值,或一条消息。模型里没有这条规则用的变量,就把变量加上。绝不为了让规则成立而把它放宽。 - 把 `Next` 写成各个动作的析取,例如 `YouPressPlay \/ YouPressStop`。不这样写,TLC 会把每一步都命名为 `Next`。 - 没有向外步骤的状态会打破 `NoDeadlock`,正确的结束状态也一样。已经有同名的 INVARIANT 或 PROPERTY 时,这条规则是 `CHECK_DEADLOCK`。在 `Next` 里加上一个动作,它只在结束状态为真,而且什么都不改,例如 `Done == phase \in {"paid", "failed"} /\ UNCHANGED vars`,再在 `step()` 里给它一个标签。 ## 选定图 需要判断的工作由你来做:每个状态和每条箭头上的词、阶段和颜色、标题,以及交给阅读者的报告。把这些写进 view 模块,用 `--view` 传进去。 要让图上出现阅读者的用词,view 得导出 `state(vars)`。`state()` 返回的值决定图的样子: - 字符串给出一张扁平图:`export const state = (v) => (v.paid ? "Paid" : "Paying");` - 数组给出父状态:`export const state = (v) => v.main.split(".");` - 对象为每个键给出一块并行区域:`export const state = (v) => ({ Playback: v.playback, Volume: v.volume });` 状态标签写阅读者看得见、或者在意的事,例如「支付中」或「租约还在,写入未完成」。标签里不要放变量名。在 `vars` 里,TLA+ 序列是从 1 起编键的对象,所以 `v.pc[1]` 就是 `pc[1]`。集合是数组。 view 还可以导出 `step(action, from, to)`。它收到 TLC 的动作名,以及这一步之前和之后的值,返回箭头的标签。每一步的标签写成用户眼中发生的事,例如「你按下播放」或「连接失败」。不要写代码的名字,也不要写 TLA+ 动作名。两个动作在图里的结果相同时,用同一个标签,这样它们共用一条箭头。 某一步只在某些条件下才会发生时,把条件用方括号写在标签末尾,用阅读者的话,例如 `you press play [while the file loads]`。在区域图里,命令会把其他区域上的条件写到箭头上,用词跟那些区域的标签一致,例如 `[when Offline]`。你写的方括号会换掉这段条件,从同一个状态出发的两条箭头就可能长得一样。所以在区域图里,别的区域上的条件不要再写方括号。步骤往哪走取决于一个标签里没出现的值时,在标签里写明结果,例如「名单读取失败」。 view 还可以导出这些: - `group(vars)` 返回阶段的名字。每个图状态用它所在分组的颜色。同一个图状态背后的模型状态分属不同分组时,这个状态不着色。 - `colors` 给每个分组名一个颜色 class。 - `title` 是显示在图顶部的字符串。 对每个模型状态,命令最多调用一次 `state()` 和 `group()`。对每一步,最多调用一次 `step()`。图和报告都用这些结果。所以每个函数只依赖自己的参数。 停在同一个标签里的步骤,图不画。阅读者必须看到这种步骤时,把标签拆开。 箭头尽量控制在大约 20 条以内,再密就难读。先让 `state()` 返回更粗的标签。行为一样的值共用一个标签,阅读者不需要的细节就省掉,比如一次还在途中、返回之后什么也不改的调用。bug 路径上的每个状态都留下,每个标记也留下。合并要是把一个 `breaks` 状态变成 `mayBreak`,规则在哪里被打破就看不见了。打破不同规则的两个状态不要合并,不然阅读者分不清哪条规则是在哪里被打破的。图还是太密的话,对阅读者不需要的步骤返回 `null`,这个值从 `step()` 来,比如每个状态都有的重置,或者一条箭头只是重复别的箭头已经画出的内容。隐藏步骤时遵守这些规则: - 每个图状态都要能从某个起始状态沿着箭头走到。 - 模型里有向外步骤的图状态,至少留一条向外的箭头。 - 一条箭头上的步骤,要么全部隐藏,要么一个不藏。只藏一部分,它的条件会变窄。 - 交接时说明图隐藏了哪些步骤。 ## 读报告 - 图里,打破规则的状态带有 class `breaks`。背后只有一部分模型状态打破了规则时,带有 class `mayBreak`。图例写着每个标记对应的规则。两条规则同时被打破时,图例把两条写在同一个标记上,所以交接时要说明哪个状态打破了哪条规则。在区域图里,包含某个状态的每一种区域组合都可能打破规则时,这个状态会得到标记。某个组合可能打破规则,里面却没有任何状态带标记,那么这个组合里的每个状态都会得到标记。 - TLC 会走过打破规则的状态,所以图上能看到 bug 之后的状态。 - TLC 会走过 bug,状态数量没有上限的模型就可能一直跑下去。常量留小,或者加上 CONSTRAINT。 - 有 VIEW 或 SYMMETRY 时,TLC 把视为相同的状态计成一个状态,图也只画这一个。箭头可能指向它,而不是步骤真正到达的状态。报告里会说明。 - TLC 会检查 CONSTRAINT 或 ACTION_CONSTRAINT 之外每个状态里的规则,但不会探索那个状态,也不检查它是否死锁。某条规则的最短路径停在这种状态上时,图会画出这个状态,报告会给出这条路径。界限之外的其他状态,图不画。这种状态里的死锁不会出现。ACTION_CONSTRAINT 排除掉的每一步,TLC 也会在这一步之后检查规则,就算下一步是从别的路径到达的也一样。某条规则的最短路径以这样的一步结束时,图会画出这一步。 - 命令按写好的配置,用一个 worker 跑 TLC 来检查规则。有规则被打破,命令就去掉这条规则再跑一次,直到没有规则被打破。第一次打破之后,每次运行到 100,000 个不同状态就停,大模型才不会一直跑下去。某次运行到了这个上限,或者因为出错停下,报告就在「未检查的规则」下面列出没检查的规则,图也不给它们打标记。没检查的规则可能成立,也可能被打破。要检查它,把已经打破的规则从配置里去掉,或者把模型缩小。加上这个上限时会多一个模块,TLC 排列变量的顺序会变,所以对一条性质,找到的反例可能和没有上限的那次运行不一样。 - `tlc.out` 是 TLC 按写好的配置打印的内容。图上没有某条被打破规则的 bug 路径时,`tlc-RULE.out` 是找到它的那次运行里 TLC 打印的内容。TLC 把第一条警告再打一遍时,普通 TLC 会输出两次,`tlc.out` 只显示一次,因为第二份不在本命令读到的输出里。只有 Java 带着 `-XX:+UseParallelGC` 运行时才会这样。否则 TLC 的第一条警告是建议加上这个标志,而且这条建议只打印一次。 ## 展示图 把 `chart.mmd` 作为 `mermaid` 代码块给用户看。图的预算是 500 个状态,数量由 TLC 按写好的配置来数。超过之后,图只画通往被打破规则的路径。一条规则都没打破时,命令不写 `chart.mmd`。每条规则仍会检查,报告里有状态数量,也有每条 bug 路径。要看整张图,把模型缩小。 用 Pele 来渲染。用户要图片,或者图大到没法当成文本来读,就按 `references/render.md` 做。用户没有另作要求时,不要换别的渲染器。 ## 交接 把每张图和它的 Mermaid 文本交给要做决定的人。每个 bug 写一行:规则、阅读者用来描述这条规则的句子、报告里编好号的路径。说明模型省略了什么。给出重新生成这些文件的命令,用一个新的 `--out` 目录。 模型描述的是代码时,把每条 bug 路径拿到真实代码上重放,做成测试,或当场复现,一个动作一步。bug 没有发生,就先当模型是错的,直到你证明它没错。