pi-t3-pstack 0.0.0-stage → 0.1.0

package/pstack/skills/statechart/scripts/test/plain-tlc.test.ts

@@ -0,0 +1,255 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { agrees, skip } from "./tlc.ts";
+
+const late = [
+  "---- MODULE Late ----",
+  "EXTENDS Naturals, TLC",
+  "CONSTANT Mode",
+  "VARIABLES x",
+  "f == [i \\in 0..2 |-> 0]",
+  "Init == x = 0",
+  "Grow == x < 5 /\\ x' = x + 1",
+  'Bad == x = 3 /\\ \\/ Mode = "assert" /\\ Assert(FALSE, "late error") /\\ x\' = 0',
+  '                \\/ Mode = "div" /\\ x\' = 1 \\div 0',
+  "Next == Grow \\/ Bad",
+  "Small == x < 1",
+  "Below == x < 2",
+  "InDomain == f[x] = 0",
+  "====",
+];
+const lateCfg = (mode: string, rules: string) =>
+  `CONSTANT Mode = "${mode}"\nINIT Init\nNEXT Next\nINVARIANTS ${rules}\n`;
+
+test(
+  "a rule that breaks before another rule fails to evaluate breaks in either order",
+  { skip },
+  () => {
+    const first = agrees("Late", { Late: late }, lateCfg("none", "Below InDomain"));
+    const last = agrees("Late", { Late: late }, lateCfg("none", "InDomain Below"));
+    assert.equal(first.status, 1);
+    assert.deepEqual(first.breaks, new Map([["Below", 2]]));
+    assert.deepEqual(first.holds, []);
+    assert.deepEqual(first.unchecked, ["InDomain", "NoDeadlock"]);
+    assert.deepEqual(last, first);
+  },
+);
+
+test("a rule that breaks before a step fails to evaluate breaks", { skip }, () => {
+  for (const mode of ["div", "assert"]) {
+    const v = agrees("Late", { Late: late }, lateCfg(mode, "Small"));
+    assert.equal(v.status, 1);
+    assert.deepEqual(v.breaks, new Map([["Small", 1]]));
+    assert.deepEqual(v.unchecked, ["NoDeadlock"]);
+  }
+});
+
+const warnPath = (next: string) => [
+  "---- MODULE WarnPath ----",
+  "EXTENDS Naturals",
+  "VARIABLES x",
+  "f == [i \\in 0..1 |-> i]",
+  "Init == x = 0",
+  "One == x < 3 /\\ x' = x + 1",
+  "Two == x < 3 /\\ x' = x + 2",
+  `Next == ${next}`,
+  "Zero == f[x] = 0",
+  "====",
+];
+
+test("a rule that breaks before it fails to evaluate breaks", { skip }, () => {
+  const v = agrees(
+    "WarnPath",
+    { WarnPath: warnPath("One \\/ Two") },
+    "INIT Init\nNEXT Next\nINVARIANT Zero\n",
+  );
+  assert.equal(v.status, 1);
+  assert.equal(v.breaks.get("Zero"), 1);
+});
+
+test("a rule that fails to evaluate before TLC reaches a break exits 2", { skip }, () => {
+  for (const deadlock of ["", "CHECK_DEADLOCK FALSE\n"]) {
+    const v = agrees(
+      "WarnPath",
+      { WarnPath: warnPath("Two \\/ One") },
+      `INIT Init\nNEXT Next\nINVARIANT Zero\n${deadlock}`,
+    );
+    assert.equal(v.status, 2);
+    assert.deepEqual(v.holds, []);
+  }
+});
+
+test("a rule that no verdict run checks stays not checked under a SYMMETRY", { skip }, () => {
+  const v = agrees(
+    "Hide",
+    {
+      Hide: [
+        "---- MODULE Hide ----",
+        "EXTENDS Naturals, TLC",
+        "CONSTANTS a, b, S",
+        "VARIABLES x, n",
+        "Perms == Permutations(S)",
+        "Init == x \\in S /\\ n = 0",
+        "Next == n < 4 /\\ n' = n + 1 /\\ UNCHANGED x",
+        "Early == n # 1",
+        "Bad == x = a",
+        'Boom == n < 3 \\/ Assert(FALSE, "boom")',
+        "====",
+      ],
+    },
+    "CONSTANTS a = a b = b S = {a, b}\nSYMMETRY Perms\nINIT Init\nNEXT Next\nINVARIANTS Early Boom Bad\n",
+  );
+  assert.equal(v.status, 1);
+  assert.deepEqual(v.breaks, new Map([["Early", 1]]));
+  assert.deepEqual(v.holds, []);
+  assert.deepEqual(v.unchecked, ["Bad", "Boom", "NoDeadlock"]);
+});
+
+test("a deadlock breaks whatever shape the SPECIFICATION has", { skip }, () => {
+  const live = agrees(
+    "Live",
+    {
+      Live: [
+        "---- MODULE Live ----",
+        "EXTENDS Naturals",
+        "VARIABLE x",
+        "Init == x = 0",
+        "Next == x < 2 /\\ x' = x + 1",
+        "Spec == Init /\\ [][Next]_x",
+        "LiveSpec == Spec /\\ WF_x(Next)",
+        "TypeOK == x \\in 0..2",
+        "====",
+      ],
+    },
+    "SPECIFICATION LiveSpec\nINVARIANT TypeOK\n",
+  );
+  assert.deepEqual(live.breaks, new Map([["NoDeadlock", 2]]));
+  assert.deepEqual(live.holds, ["TypeOK"]);
+  for (const next of ["[][Next \\/ Tick]_vars", "[][\\E i \\in 1..2 : Step(i)]_vars"]) {
+    const v = agrees(
+      "Shape",
+      {
+        Shape: [
+          "---- MODULE Shape ----",
+          "EXTENDS Naturals",
+          "VARIABLES x, t",
+          "vars == <<x, t>>",
+          "Init == x = 0 /\\ t = 0",
+          "Step(i) == x < 2 /\\ x' = x + i /\\ UNCHANGED t",
+          "Next == Step(1)",
+          "Tick == t < 1 /\\ t' = 1 /\\ UNCHANGED x",
+          `Spec == Init /\\ ${next}`,
+          "====",
+        ],
+      },
+      "SPECIFICATION Spec\n",
+    );
+    assert.equal(v.status, 1);
+    assert.ok(v.breaks.has("NoDeadlock"));
+  }
+});
+
+test("a SPECIFICATION from an INSTANCE checks deadlock and finds none", { skip }, () => {
+  const v = agrees(
+    "Outer",
+    {
+      Inner: [
+        "---- MODULE Inner ----",
+        "EXTENDS Naturals",
+        "VARIABLE x",
+        "Spec == x = 0 /\\ [][x' = (x + 1) % 3]_x",
+        "====",
+      ],
+      Outer: [
+        "---- MODULE Outer ----",
+        "VARIABLE x",
+        "I == INSTANCE Inner",
+        "Spec == I!Spec",
+        "====",
+      ],
+    },
+    "SPECIFICATION Spec\n",
+  );
+  assert.equal(v.status, 0);
+  assert.deepEqual(v.holds, ["NoDeadlock"]);
+});
+
+test("a state at a CONSTRAINT bound is no deadlock", { skip }, () => {
+  const v = agrees(
+    "Bound",
+    {
+      Bound: [
+        "---- MODULE Bound ----",
+        "EXTENDS Naturals",
+        "VARIABLE x",
+        "Init == x = 0",
+        "Next == x' = x + 1",
+        "Small == x < 3",
+        "====",
+      ],
+    },
+    "INIT Init\nNEXT Next\nCONSTRAINT Small\n",
+  );
+  assert.equal(v.status, 0);
+  assert.deepEqual(v.holds, ["NoDeadlock"]);
+  assert.doesNotMatch(v.chart, /^ {2}class s\d+ breaks$/m);
+});
+
+test(
+  "a model with no initial state passes as it does in TLC, and the report says why",
+  { skip },
+  () => {
+    const v = agrees(
+      "NoInit",
+      {
+        NoInit: [
+          "---- MODULE NoInit ----",
+          "EXTENDS Naturals",
+          "VARIABLE x",
+          "Init == x = 0 /\\ x > 0",
+          "Next == x' = x + 1",
+          "Small == x < 3",
+          "====",
+        ],
+      },
+      "INIT Init\nNEXT Next\nINVARIANT Small\n",
+    );
+    assert.equal(v.status, 0);
+    assert.deepEqual(v.holds, ["NoDeadlock", "Small"]);
+    assert.match(
+      v.report,
+      /^TLC found no state that satisfies Init, so no state can break a rule\.$/m,
+    );
+  },
+);
+
+test(
+  "a run after a break stops at the state bound and leaves its rules not checked",
+  { skip },
+  () => {
+    const v = agrees(
+      "Cycle",
+      {
+        Cycle: [
+          "---- MODULE Cycle ----",
+          "EXTENDS Naturals",
+          "VARIABLE x",
+          "Next == x' = (x + 1) % 100005",
+          "Spec == x = 0 /\\ [][Next]_x /\\ WF_x(Next)",
+          "Early == x # 3",
+          "Back == []<>(x = 0)",
+          "====",
+        ],
+      },
+      "SPECIFICATION Spec\nINVARIANT Early\nPROPERTY Back\n",
+    );
+    assert.equal(v.status, 1);
+    assert.deepEqual(v.breaks, new Map([["Early", 3]]));
+    assert.deepEqual(v.holds, []);
+    assert.deepEqual(v.unchecked, ["Back", "NoDeadlock"]);
+    assert.match(
+      v.report,
+      /^After the first break, each TLC run stops at 100,000 distinct states\./m,
+    );
+  },
+);

package/pstack/skills/statechart/scripts/test/render.test.ts

@@ -0,0 +1,81 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { before, test } from "node:test";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { fuzz, type Html, type Mermaid, type Render } from "./labels.ts";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const charts = [];
+for (const f of fs.readdirSync(path.join(here, "charts")))
+  charts.push(path.join(here, "charts", f));
+for (const d of fs.readdirSync(path.join(here, "corpus")))
+  charts.push(path.join(here, "corpus", d, "chart.mmd"));
+const guide = fs.readFileSync(path.join(here, "../../references/render.md"), "utf8");
+const css = guide.match(/```css\n([\s\S]*?)```/);
+assert.ok(css, "references/render.md has no css block");
+const theme = css[1];
+const cache = path.join(
+  process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), ".cache"),
+  "statechart",
+);
+const install = (name: string, ...packages: string[]) => {
+  const dir = path.join(cache, name);
+  execFileSync(
+    "npm",
+    ["install", "--prefix", dir, "--no-audit", "--no-fund", "--save-exact", ...packages],
+    { stdio: ["ignore", "pipe", "pipe"] },
+  );
+  return createRequire(path.join(dir, "package.json"));
+};
+
+let render: Render;
+let mermaid: Mermaid;
+let html: Html;
+before(async () => {
+  const pele = install("test-pele-1.9.0", "pele@1.9.0");
+  ({ render } = await import(pathToFileURL(pele.resolve("pele")).href));
+
+  const parser = install("test-mermaid-11.16.0", "mermaid@11.16.0", "jsdom@26.1.0");
+  const { window } = new (parser("jsdom").JSDOM)("");
+  Object.assign(globalThis, { window, document: window.document, DOMParser: window.DOMParser });
+  mermaid = (await import(pathToFileURL(parser.resolve("mermaid")).href)).default;
+  html = (markup) => {
+    const t = window.document.createElement("template");
+    t.innerHTML = markup;
+    return t.content.textContent ?? "";
+  };
+});
+
+const classes = new Set<string>();
+for (const chart of charts) {
+  const name = path.relative(here, chart);
+  const text = fs.readFileSync(chart, "utf8");
+  const marks = [...text.matchAll(/^ {2}class (\w+) (\w+)$/gm)];
+  for (const [, , mark] of marks) classes.add(mark);
+
+  test(`${name} renders in Pele 1.9.0 with each class on its node`, () => {
+    const { svg } = render(text);
+    assert.match(svg, /^<svg /);
+    for (const [, id, mark] of marks)
+      assert.match(svg, new RegExp(`class="pele-node[^"]* ${mark}\\b[^"]*" data-id="${id}"`), id);
+  });
+
+  test(`${name} parses in mermaid.js, which chat views use`, async () => {
+    await mermaid.parse(text);
+  });
+}
+
+test("random labels and colors keep their text and the chart's shape in Mermaid and Pele", async () => {
+  const { drawn, refused, failure } = await fuzz({ seed: 1, charts: 500, render, mermaid, html });
+  if (failure) assert.fail(failure);
+  assert.ok(drawn > 400 && refused > 20, `${drawn} charts drawn, ${refused} refused`);
+});
+
+test("the theme in references/render.md colors each class that the charts use", () => {
+  assert.ok(classes.size > 0);
+  for (const name of classes) assert.match(theme, new RegExp(`\\.pele \\.${name} rect \\{`), name);
+});

package/pstack/skills/statechart/scripts/test/tlc-out.test.ts

@@ -0,0 +1,90 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { plainText } from "../backends/plain-text.ts";
+import { readMessages } from "../frontends/messages.ts";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const corpus = path.join(here, "corpus");
+const skip = !process.env.TLA2TOOLS && "set TLA2TOOLS to the path of tla2tools.jar to run TLC";
+const read = (file: string) => fs.readFileSync(file, "utf8");
+const maybe = (file: string) => (fs.existsSync(file) ? read(file) : "");
+const plain = (text: string) => [...plainText(readMessages(text))].join("");
+
+const steady = (text: string) =>
+  text
+    .replace(/"chart-[0-9a-f]{32}"/g, '"chart"')
+    .replace(/\bfp \d+ and seed -?\d+/g, "fp _ and seed _")
+    .replace(/\[pid: \d+\]/g, "[pid: _]")
+    .replace(/\d{4}-\d\d-\d\d \d\d:\d\d:\d\d/g, "_")
+    .replace(/ \([\d,]+ d?s\/min\)/g, "")
+    .replace(/ in (?:\d+d \d\dh|\d\dh \d\dmin|\d\dmin \d\ds|\d\ds) at /g, " in _ at ");
+
+test(
+  "each corpus spec's TLC output reads as plain TLC prints it at -workers 1",
+  { skip, concurrency: 4 },
+  async (t) => {
+    await Promise.all(
+      fs.readdirSync(corpus).map((name) =>
+        t.test(name, async () => {
+          const dir = path.join(corpus, name);
+          const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "statechart-plain-"));
+          const [tool, twin, out] = ["tool", "plain", "out"].map((f) => path.join(tmp, f));
+          fs.mkdirSync(tool);
+          fs.mkdirSync(twin);
+          const view = path.join(dir, "view.mjs");
+          const child = spawn(
+            process.execPath,
+            [
+              path.join(here, "../statechart.ts"),
+              path.join(dir, `${name}.tla`),
+              ...(fs.existsSync(view) ? ["--view", view] : []),
+              "--out",
+              out,
+            ],
+            {
+              env: {
+                ...process.env,
+                JAVA: path.join(here, "java.ts"),
+                STATECHART_JAVA: process.env.JAVA ?? "java",
+                STATECHART_RECORD: tool,
+                STATECHART_PLAIN: twin,
+              },
+              stdio: ["ignore", "ignore", "pipe"],
+            },
+          );
+          let stderr = "";
+          child.stderr.on("data", (chunk: Buffer) => (stderr += chunk));
+          await once(child, "close");
+          assert.equal(stderr, "");
+          const runs = fs.readdirSync(twin).filter((f) => f.endsWith(".out"));
+          assert.ok(runs.includes("ChartRun.out"), "the drawing run has a plain twin");
+          for (const run of runs) {
+            const exit = run.replace(/\.out$/, ".exit");
+            assert.equal(maybe(path.join(tool, exit)), maybe(path.join(twin, exit)), exit);
+            assert.equal(
+              steady(plain(read(path.join(tool, run)))),
+              steady(read(path.join(twin, run))),
+              run,
+            );
+          }
+          assert.equal(
+            steady(read(path.join(out, "tlc.out"))),
+            steady(`${read(path.join(twin, "verdict-1.out"))}\n`),
+          );
+          const verdicts = new Set<string>();
+          for (const run of runs)
+            if (run.startsWith("verdict-")) verdicts.add(steady(`${read(path.join(twin, run))}\n`));
+          for (const f of fs.readdirSync(out))
+            if (/^tlc-\w+\.out$/.test(f))
+              assert.ok(verdicts.has(steady(read(path.join(out, f)))), f);
+        }),
+      ),
+    );
+  },
+);

package/pstack/skills/statechart/scripts/test/tlc.ts

@@ -0,0 +1,158 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { PINNED_FLAGS } from "../run.ts";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const jar = process.env.TLA2TOOLS;
+export const skip = !jar && "set TLA2TOOLS to the path of tla2tools.jar to run TLC";
+
+const RULES = /^(INVARIANTS?|PROPERTY|PROPERTIES|CHECK_DEADLOCK)$/;
+
+const exitClass = (status: number | null) =>
+  status === 0 ? 0 : status === 11 || status === 12 || status === 13 ? 1 : 2;
+
+const stepsIn = (text: string) =>
+  Math.max((text.match(/^State \d+: (?!Stuttering$)/gm)?.length ?? 0) - 1, 0) +
+  (text.match(/^Back to state \d+: </gm)?.length ?? 0);
+
+function properties(cfg: string) {
+  const names: string[] = [];
+  let section = "";
+  for (const line of cfg.split("\n")) {
+    section = line.match(/^[A-Z_]+/)?.[0] ?? section;
+    if (/^PROPERT(Y|IES)$/.test(section))
+      for (const word of line.trim().split(/\s+/)) if (word && word !== section) names.push(word);
+  }
+  return names;
+}
+
+function tlc(dir: string, module: string, cfg: string) {
+  const run = `alone-${fs.readdirSync(dir).length}`;
+  const file = path.join(dir, `${run}.cfg`);
+  fs.writeFileSync(file, cfg);
+  const tmp = path.join(dir, `${run}-tmp`);
+  fs.mkdirSync(tmp);
+  const r = spawnSync(
+    process.env.JAVA ?? "java",
+    [
+      `-Djava.io.tmpdir=${tmp}`,
+      "-cp",
+      jar ?? "",
+      "tlc2.TLC",
+      ...PINNED_FLAGS,
+      "-config",
+      file,
+      "-metadir",
+      path.join(dir, `${run}-meta`),
+      module,
+    ],
+    { cwd: dir, encoding: "utf8" },
+  );
+  const out = r.stdout + r.stderr;
+  const temporal = properties(cfg);
+  const broke =
+    out.match(/^Error: (?:Invariant|Action property|Property) (\S+) is violated/m)?.[1] ??
+    (/^Error: Deadlock reached\./m.test(out) ? "NoDeadlock" : undefined) ??
+    (/^Error: Temporal properties were violated\./m.test(out) && temporal.length === 1
+      ? temporal[0]
+      : undefined);
+  return { status: r.status, out, broke, steps: stepsIn(out) };
+}
+
+function alone(cfg: string, rule: string) {
+  const lines: string[] = [];
+  let section = "";
+  for (const line of cfg.split("\n")) {
+    section = line.match(/^[A-Z_]+/)?.[0] ?? section;
+    if (!RULES.test(section)) lines.push(line);
+  }
+  if (rule !== "NoDeadlock")
+    lines.push(
+      `${properties(cfg).includes(rule) ? "PROPERTY" : "INVARIANT"} ${rule}`,
+      "CHECK_DEADLOCK FALSE",
+    );
+  return `${lines.join("\n")}\n`;
+}
+
+export type Verdict = {
+  status: number | null;
+  breaks: Map<string, number>;
+  holds: string[];
+  unchecked: string[];
+  chart: string;
+  report: string;
+};
+
+export function agrees(module: string, files: { [name: string]: string[] }, cfg: string): Verdict {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "statechart-plain-"));
+  try {
+    for (const [name, lines] of Object.entries(files))
+      fs.writeFileSync(path.join(dir, `${name}.tla`), `${lines.join("\n")}\n`);
+    fs.writeFileSync(path.join(dir, `${module}.cfg`), cfg);
+    const out = path.join(dir, "out");
+    const cli = spawnSync(
+      process.execPath,
+      [path.join(here, "../statechart.ts"), path.join(dir, `${module}.tla`), "--out", out],
+      { encoding: "utf8" },
+    );
+    const plain = tlc(dir, module, cfg);
+    const report = fs.existsSync(out) ? fs.readFileSync(path.join(out, "report.md"), "utf8") : "";
+    const shown = `${cli.stderr}${report}`;
+    assert.equal(
+      cli.status,
+      exitClass(plain.status),
+      `TLC says:\n${plain.out}\nThe command says:\n${shown}`,
+    );
+    assert.doesNotMatch(shown, /Chart\w*Mark/);
+    if (cli.status !== 2) assert.equal(cli.stderr, "");
+    if (!report) assert.match(cli.stderr, /TLC could not check/);
+    if (cli.status === 2) {
+      const error = plain.out.match(/^Error: .*$/m)?.[0];
+      assert.ok(
+        error && shown.includes(error),
+        `TLC says:\n${plain.out}\nThe command says:\n${shown}`,
+      );
+    }
+
+    const breaks = new Map<string, number>();
+    const bounded = new Set<string>();
+    for (const [, rule, body] of report.matchAll(/^## (\S+) breaks\n(.*)$/gm)) {
+      const said = body.match(/has (\d+) steps?:/)?.[1];
+      const file = body.match(/ is in (tlc-\S+\.out)\./)?.[1];
+      if (!file) {
+        breaks.set(rule, Number(said));
+        continue;
+      }
+      const text = fs.readFileSync(path.join(out, file), "utf8");
+      if (said) assert.equal(Number(said), stepsIn(text), rule);
+      if (/^Semantic processing of module ChartBound$/m.test(text)) bounded.add(rule);
+      breaks.set(rule, stepsIn(text));
+    }
+    const list = (title: string) =>
+      report
+        .match(new RegExp(`^## ${title}\\n(.*)$`, "m"))?.[1]
+        .split(", ")
+        .sort() ?? [];
+    const holds = list("Rules that hold");
+    const unchecked = list("Rules not checked");
+    const chartFile = path.join(out, "chart.mmd");
+    const chart = fs.existsSync(chartFile) ? fs.readFileSync(chartFile, "utf8") : "";
+    if (plain.broke) assert.equal(breaks.get(plain.broke), plain.steps, shown);
+    for (const rule of holds) {
+      const r = tlc(dir, module, alone(cfg, rule));
+      assert.equal(r.status, 0, `${rule} holds in the report, but TLC says:\n${r.out}`);
+    }
+    for (const [rule, steps] of breaks) {
+      const r = tlc(dir, module, alone(cfg, rule));
+      assert.equal(r.broke, rule, `${rule} breaks in the report, but TLC says:\n${r.out}`);
+      if (!bounded.has(rule)) assert.equal(steps, r.steps, rule);
+    }
+    return { status: cli.status, breaks, holds, unchecked, chart, report };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}

package/pstack/skills/statechart/scripts/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "noEmit": true,
+    "strict": true,
+    "allowImportingTsExtensions": true,
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
+    "module": "nodenext",
+    "types": ["node"]
+  }
+}

package/pstack/skills/statechart/scripts/worker.ts

@@ -0,0 +1,35 @@
+import { Buffer } from "node:buffer";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { inspect } from "node:util";
+import { checkView } from "./frontends/view.ts";
+import { compile } from "./pipeline.ts";
+import { check, messageOf } from "./run.ts";
+
+const [stage, specFile, configFile, viewFile] = process.argv.slice(2);
+
+try {
+  const view = checkView(
+    viewFile ? await import(pathToFileURL(path.resolve(viewFile)).href) : {},
+    inspect,
+  );
+  const { files, exit } = compile(await check(specFile, configFile), view);
+  const draft = path.join(stage, "draft");
+  fs.mkdirSync(draft);
+  for (const [name, parts] of files) {
+    const fd = fs.openSync(path.join(draft, name), "wx");
+    try {
+      for (const part of parts)
+        fs.writeSync(fd, typeof part === "string" ? Buffer.from(part) : part);
+      fs.writeSync(fd, "\n");
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
+  fs.renameSync(draft, path.join(stage, "done"));
+  process.exit(exit);
+} catch (error) {
+  console.error(messageOf(error));
+  process.exit(2);
+}

package/pstack/skills/swarm/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: swarm
+description: "Fan out N parallel workers, drain them, and return one report. Use for /swarm, 'swarm this', or parallel coverage, races, gauntlets, and exploration."
+disable-model-invocation: true
+---
+
+# Swarm
+
+## Start
+
+Open a todolist with one entry per phase before launching anything.
+
+1. Frame
+2. Fan out
+3. Aggregate
+4. Report
+
+## Phase A: Frame
+
+1. State the done predicate and the artifact or report the swarm must return.
+2. Choose the shape. Partition into slices, race N workers on identical briefs, or mix both. For a race or mixed shape, declare `first pass`, `rank all`, or `best-of` before spawning.
+3. Get the worker target from `pstack_model` with `swarm workers`. When it returns `inherit-parent`, omit `target` so the workers run on the parent model. For a model race, name each arm's model up front. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill.
+4. Give each worker its own writable output when it writes. When workers verify or measure commits, each brief names the exact SHAs. A measurement brief also names the method (sample count, what one sample is, order). The worker records both in its result.
+
+## Phase B: Fan out
+
+Spawn all N workers in one response as `delegate_task` calls with `mode: "async"` and the step 3 `target`, left unset for `auto` or `inherit-parent`. Every worker runs on this machine, so a worker that writes gets its own git worktree, named by absolute path in its brief as the only place it writes.
+
+When a worker must start from a non-default branch, create its worktree from that branch.
+
+Every brief stands alone. Include the goal, scope, exact slice or race arm, how to verify, and what to report. Reports use `PASS`, `ISSUES`, or `BLOCKED` with evidence. A worker that can prove a defect reports `ISSUES` and lists every issue it can prove, not only the first.
+
+If a worker drops out, proceed with N-1 and note it.
+
+## Phase C: Aggregate
+
+Read the terminal results. Drop a result that does not record the SHAs and method its brief names, and respawn that worker once. After a second miss, record a gap. A gap does not count as a pass. For coverage, every required slice needs a result. For a race, apply the selection rule declared up front. Use first pass, rank all, or best-of. Do not paste raw worker dumps.
+
+## Phase D: Report
+
+Return one consolidated in-chat report with a result table, issue one-liners, gaps or dropouts, and the race rule when used.
+
+## Models
+
+Get every target from the `pstack_model` tool. Pass the role name plus the job type and size from the routing table in poteto-mode's Subagents section. This skill's spawns are `check` jobs for verification workers and `implement` or `mechanical` jobs for build workers. Write every brief from `<plugin root>/skills/poteto-mode/brief.md`: the extension refuses a `delegate_task` call whose brief is missing its sections or limits. Without a job, pass the complexity: `groundwork` for cheap mechanical work, `bounded` for involved but bounded work, `general` for work that needs substantial judgment. The tool reads the role's line in the model sheet (`~/.config/t3-pstack/models.md`, written by `/setup-pstack`). A line naming a model is used as written, moved to a provider T3 can run right now when needed. A role with no line, or `inherit-parent` or `auto`, is routed by this extension's `models.json`: the parent's model family, sized and reasoned by complexity, and for panels one seat per family. The extension blocks a `delegate_task` call that uses the reserved Fable model or fast mode unless the user named it, reasoning above what `pstack_model` returned, or reasoning above high unless the user's latest message is "allow xhigh". Pass each returned target as `delegate_task`'s `target`. `inherit-parent` means omit `target`. `blocked` means the panel cannot reach two model families on this T3, so record its reason.
+
+- swarm workers: one target