pi-pstack-native 0.0.0-stage → 1.0.0

package/dist/statechart/run.js

@@ -0,0 +1,432 @@
+import { Buffer } from "node:buffer";
+import { execFile, spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { inspect } from "node:util";
+import { boundRun, chartRun, configText } from "./backends/cfg.js";
+import { plainText } from "./backends/plain-text.js";
+import { readConfig } from "./frontends/config.js";
+import { parseDot } from "./frontends/dot.js";
+import { readCounterexample, readMarks } from "./frontends/marks.js";
+import { readMessages } from "./frontends/messages.js";
+import { initialOnlyProperties, readChecks, readSany, readSpec } from "./frontends/spec.js";
+import { readTrace } from "./frontends/trace.js";
+import { readVerdict } from "./frontends/verdict.js";
+import { CHART_STATES, hasSection, LEVEL, must, PART, RERUN_STATES, ruleKey, stateRules, } from "./ir.js";
+import { addPast, deadEnds, finder, lasso, mark } from "./passes/annotate.js";
+import { pathGraph } from "./passes/paths.js";
+export function* fileLines(file) {
+    const fd = fs.openSync(file, "r");
+    try {
+        let buf = Buffer.allocUnsafe(PART);
+        let kept = 0;
+        for (;;) {
+            if (kept === buf.length)
+                buf = Buffer.concat([buf], buf.length * 2);
+            const n = fs.readSync(fd, buf, kept, buf.length - kept, null);
+            if (!n)
+                break;
+            const end = kept + n;
+            const cut = buf.lastIndexOf(10, end - 1);
+            if (cut === -1) {
+                kept = end;
+                continue;
+            }
+            yield* buf.toString("utf8", 0, cut).split("\n");
+            kept = buf.copy(buf, 0, cut + 1, end);
+        }
+        yield buf.toString("utf8", 0, kept);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+const TLC_TOOL = "http:tla2tools[url=https://github.com/tlaplus/tlaplus/releases/download/v1.7.4/tla2tools.jar,checksum=sha256:936a262061c914694dfd669a543be24573c45d5aa0ff20a8b96b23d01e050e88]@1.7.4";
+const JAVA_TOOL = "java@temurin-25";
+export const PINNED_FLAGS = ["-workers", "1", "-fp", "0", "-lncheck", "final"];
+const runChild = (file, args, options) => new Promise((resolve) => {
+    execFile(file, args, { encoding: "utf8", maxBuffer: 1 << 30, ...options }, (error, stdout, stderr) => resolve({
+        status: error ? (typeof error.code === "number" ? error.code : null) : 0,
+        stdout,
+        stderr,
+        error: typeof error?.code === "string" ? error : undefined,
+    }));
+});
+export const killGroup = (pid) => new Promise((resolve) => spawn("/bin/sh", ["-c", 'kill -s KILL -- "-$1"', "sh", String(pid)], { stdio: "ignore" }).on("exit", resolve));
+export const messageOf = (error) => typeof error === "object" &&
+    error !== null &&
+    "message" in error &&
+    typeof error.message === "string"
+    ? error.message
+    : inspect(error);
+const joined = (files) => {
+    const fds = [];
+    const sizes = [];
+    for (const f of files) {
+        const fd = fs.openSync(f, "r");
+        fds.push(fd);
+        sizes.push(fs.fstatSync(fd).size);
+    }
+    return {
+        *[Symbol.iterator]() {
+            for (let f = 0; f < fds.length; f++)
+                for (let pos = 0; pos < sizes[f];) {
+                    const buf = Buffer.allocUnsafe(Math.min(PART, sizes[f] - pos));
+                    const n = fs.readSync(fds[f], buf, 0, buf.length, pos);
+                    if (!n)
+                        break;
+                    pos += n;
+                    yield buf.subarray(0, n);
+                }
+        },
+    };
+};
+const utf8 = new TextDecoder("utf-8", { ignoreBOM: true });
+function* outputLines(output) {
+    let rest = new Uint8Array(0);
+    for (const part of output) {
+        const buf = rest.length ? Buffer.concat([rest, part]) : part;
+        const cut = buf.lastIndexOf(10);
+        if (cut === -1) {
+            rest = buf;
+            continue;
+        }
+        yield* utf8.decode(buf.subarray(0, cut)).split("\n");
+        rest = buf.subarray(cut + 1);
+    }
+    yield utf8.decode(rest);
+}
+const messagesOf = (output) => ({
+    [Symbol.iterator]: () => readMessages(outputLines(output)),
+});
+const runToFiles = (file, args, { out, ...options }) => new Promise((resolve) => {
+    const files = [`${out}.stdout`, `${out}.stderr`];
+    const fds = [];
+    for (const f of files)
+        fds.push(fs.openSync(f, "w"));
+    let child;
+    try {
+        child = spawn(file, args, { ...options, stdio: ["ignore", ...fds] });
+    }
+    finally {
+        for (const fd of fds)
+            fs.closeSync(fd);
+    }
+    let error;
+    const settle = (code) => resolve({
+        status: error ? null : code,
+        stdout: files[0],
+        output: joined(files),
+        error,
+    });
+    child.on("error", (e) => {
+        error = e;
+        if (child.pid === undefined)
+            settle(null);
+    });
+    child.on("close", (code) => {
+        if (child.pid !== undefined)
+            settle(code);
+    });
+});
+async function findTlc(cwd) {
+    const { TLA2TOOLS, JAVA } = process.env;
+    if (TLA2TOOLS)
+        return { jar: TLA2TOOLS, java: JAVA || "java" };
+    const mise = (...args) => runChild("mise", args, { cwd, env: { ...process.env, MISE_CEILING_PATHS: cwd } });
+    const where = () => Promise.all([mise("where", TLC_TOOL), mise("which", "java", "--tool", JAVA_TOOL)]);
+    let found = await where();
+    if (found.some((r) => r.status !== 0)) {
+        const r = await mise("install", JAVA_TOOL, TLC_TOOL);
+        if (r.status !== 0)
+            throw new Error(`Cannot find TLC: mise install failed: ${r.error?.message ?? r.stderr.trim()}\nOr set TLA2TOOLS to the path of tla2tools.jar, and JAVA to a java binary (Java 11 or later).`);
+        found = await where();
+    }
+    return {
+        jar: path.join(found[0].stdout.trim(), "tla2tools.jar"),
+        java: JAVA || found[1].stdout.trim(),
+    };
+}
+const exitClass = (status) => status === 0 ? 0 : status === 11 || status === 12 || status === 13 ? 1 : 2;
+const tail = (r) => {
+    if (r.error)
+        return r.error.message;
+    const kept = [];
+    let size = 0;
+    for (const chunk of plainText(messagesOf(r.output))) {
+        kept.push(chunk);
+        size += chunk.length;
+        while (size - kept[0].length >= 1 << 28)
+            size -= kept.shift().length;
+    }
+    return kept.join("").trim().split("\n").slice(-30).join("\n");
+};
+const stopOf = (r) => {
+    const errors = [];
+    for (const m of r.error ? [] : messagesOf(r.output))
+        if (typeof m !== "string" &&
+            (m.level === LEVEL.ERROR ||
+                m.level === LEVEL.TLCBUG ||
+                (errors.length && m.level === LEVEL.STATE)))
+            errors.push(m);
+    if (!errors.length)
+        return { status: r.status, message: tail(r) };
+    const lines = [...plainText(errors)].join("").trim().split("\n");
+    if (lines.length > 40)
+        lines.splice(40, Infinity, `... ${lines.length - 40} more lines`);
+    return { status: r.status, message: lines.join("\n") };
+};
+const names = (rules, kind) => {
+    const found = [];
+    for (const rule of rules)
+        if (rule.kind === kind)
+            found.push(rule.name);
+    return found;
+};
+const brokenRule = (rules, broke) => {
+    if (broke.kind === "temporal")
+        return undefined;
+    for (const rule of rules)
+        if (rule.kind === broke.kind && (broke.kind === "deadlock" || rule.name === broke.name))
+            return rule;
+    if (broke.kind === "invariant")
+        for (const rule of rules)
+            if (rule.kind === "property" && rule.name === broke.name)
+                return rule;
+    return undefined;
+};
+function* only(marks, rules) {
+    for (const { values, broken } of marks) {
+        const kept = [];
+        for (const name of broken)
+            if (rules.has(name))
+                kept.push(name);
+        if (kept.length)
+            yield { values, broken: kept };
+    }
+}
+export async function check(specFile, configFile) {
+    const cfg = readConfig({ file: configFile, text: fs.readFileSync(configFile, "utf8") });
+    const checks = readChecks({ configFile, config: cfg });
+    const folder = path.dirname(path.resolve(specFile));
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "statechart-"));
+    try {
+        const tlc = await findTlc(dir);
+        const config = (name, sections, extra) => {
+            fs.writeFileSync(path.join(dir, `${name}.cfg`), configText(sections, extra));
+            return [`-metadir`, path.join(dir, `meta-${name}`), "-config", path.join(dir, `${name}.cfg`)];
+        };
+        const runJava = (name, main, args, jvm = []) => {
+            const tmp = path.join(dir, `tmp-${name}`);
+            fs.mkdirSync(tmp);
+            return runToFiles(tlc.java, [
+                `-Djava.io.tmpdir=${tmp}`,
+                `-DTLA-Library=${folder}`,
+                ...jvm,
+                "-cp",
+                tlc.jar,
+                main,
+                ...args,
+            ], {
+                cwd: dir,
+                out: path.join(dir, name),
+                env: process.platform === "darwin" ? process.env : { ...process.env, LC_ALL: "C.UTF-8" },
+            });
+        };
+        const xml = await runJava("sany", "tla2sany.xml.XMLExporter", ["-o", "-I", folder, path.resolve(specFile)], ["-XX:TieredStopAtLevel=1"]);
+        if (xml.status !== 0)
+            throw new Error(`SANY could not read ${specFile} (exit ${xml.status}):\n${tail(xml)}`);
+        const sany = readSany(fs.readFileSync(xml.stdout, "utf8"));
+        const module = path.basename(specFile, ".tla");
+        const spec = { ...readSpec({ module, sany, checks }), folder };
+        const rules = stateRules(spec);
+        const all = [...rules];
+        for (const name of spec.properties)
+            all.push({ kind: "property", name });
+        const verdicts = new Map();
+        const decide = (rule, outcome, r) => verdicts.set(ruleKey(rule), { rule, outcome, messages: r && messagesOf(r.output) });
+        const judge = async () => {
+            const groups = [all];
+            let first;
+            let stop;
+            const states = { distinct: 0, initial: 0, complete: false, cut: false };
+            for (let k = 1; groups.length;) {
+                const group = [];
+                for (const rule of groups[0])
+                    if (!verdicts.has(ruleKey(rule)))
+                        group.push(rule);
+                if (first && !group.length) {
+                    groups.shift();
+                    continue;
+                }
+                const name = `verdict-${k++}`;
+                const extra = [];
+                const invariants = names(group, "invariant");
+                const properties = names(group, "property");
+                if (invariants.length)
+                    extra.push(`INVARIANT ${invariants.join(" ")}`);
+                if (properties.length)
+                    extra.push(`PROPERTY ${properties.join(" ")}`);
+                const bounded = first !== undefined && !states.complete;
+                if (bounded)
+                    extra.push("CONSTRAINT ChartBound");
+                const r = await runJava(name, "tlc2.TLC", [
+                    "-tool",
+                    ...PINNED_FLAGS,
+                    ...(names(group, "deadlock").length ? [] : ["-deadlock"]),
+                    ...config(name, spec.written, extra),
+                    bounded ? "ChartBound" : spec.module,
+                ]);
+                first ??= r;
+                const { broke, distinct, initial } = readVerdict(messagesOf(r.output));
+                states.distinct = Math.max(states.distinct, distinct);
+                states.initial = Math.max(states.initial, initial);
+                const rule = broke && brokenRule(group, broke);
+                const cut = bounded && distinct >= RERUN_STATES;
+                if (exitClass(r.status) === 2) {
+                    stop = stopOf(r);
+                    break;
+                }
+                else if (rule)
+                    decide(rule, "broken", r);
+                else if (cut && (r.status === 0 || broke?.kind === "temporal")) {
+                    states.cut = true;
+                    for (const rule of group)
+                        decide(rule, "not checked");
+                }
+                else if (r.status === 0) {
+                    states.complete = true;
+                    for (const rule of group)
+                        decide(rule, "holds");
+                }
+                else if (broke && properties.length) {
+                    if (broke.kind === "temporal") {
+                        states.complete = true;
+                        for (const rule of group)
+                            if (rule.kind !== "property")
+                                decide(rule, "holds");
+                    }
+                    const pending = [];
+                    const rest = [];
+                    for (const rule of group)
+                        if (rule.kind === "property")
+                            pending.push([rule]);
+                        else if (!verdicts.has(ruleKey(rule)))
+                            rest.push(rule);
+                    if (pending.length === 1)
+                        decide(pending[0][0], "broken", r);
+                    else
+                        groups.splice(0, 1, rest, ...pending);
+                }
+                else
+                    throw new Error(`TLC exited ${r.status} on ${specFile}, but its output names no rule that broke:\n${tail(r)}`);
+            }
+            for (const rule of all)
+                if (!verdicts.has(ruleKey(rule)))
+                    decide(rule, "not checked");
+            return { first: first, stop, states };
+        };
+        fs.writeFileSync(path.join(dir, "ChartBound.tla"), boundRun(spec.module));
+        const judged = await judge();
+        const exit = exitClass(judged.first.status);
+        const failed = (r) => new Error(`TLC could not check ${specFile} (exit ${r.status}):\n${stopOf(r).message}`);
+        const initialOnly = initialOnlyProperties(sany, spec);
+        const propertiesWith = (bugOf) => {
+            const properties = [];
+            for (const rule of all) {
+                if (rule.kind !== "property")
+                    continue;
+                const v = must(verdicts, ruleKey(rule));
+                properties.push({
+                    ...v,
+                    bug: v.outcome === "broken" && v.messages ? bugOf(readTrace(v.messages)) : undefined,
+                    initialOnly: initialOnly.has(rule.name),
+                });
+            }
+            return properties;
+        };
+        if (exit === 2)
+            throw failed(judged.first);
+        const checked = [];
+        for (const rule of rules)
+            checked.push(must(verdicts, ruleKey(rule)));
+        const common = {
+            spec,
+            exit,
+            stop: judged.stop,
+            states: judged.states,
+            messages: messagesOf(judged.first.output),
+            rules: checked,
+        };
+        if (judged.states.distinct <= CHART_STATES) {
+            const tag = `chart-${randomBytes(16).toString("hex")}`;
+            fs.writeFileSync(path.join(dir, "ChartRun.tla"), chartRun(spec, tag));
+            const drawn = await runJava("ChartRun", "tlc2.TLC", [
+                "-tool",
+                ...PINNED_FLAGS,
+                "-deadlock",
+                ...config("ChartRun", spec.written, ["INVARIANT ChartMark", "CONSTRAINT ChartBudget"]),
+                "-dump",
+                "dot,actionlabels",
+                path.join(dir, "graph"),
+                "ChartRun",
+            ]);
+            const file = path.join(dir, "graph.dot");
+            if (!fs.existsSync(file))
+                throw failed(drawn);
+            if (readVerdict(messagesOf(drawn.output)).distinct <= CHART_STATES) {
+                const graph = parseDot(fileLines(file));
+                const find = finder(graph, spec.variables);
+                const drawing = drawn.status === 0 ? undefined : { status: drawn.status };
+                const broken = new Set();
+                for (const { rule, outcome } of verdicts.values())
+                    if (rule.kind === "invariant" && outcome === "broken")
+                        broken.add(rule.name);
+                const marks = only(readMarks(readMessages(fileLines(drawn.stdout)), tag), broken);
+                const past = mark(graph, marks, spec.variables, rules, find);
+                const excludes = hasSection(spec, "ACTION_CONSTRAINT");
+                for (const rule of rules) {
+                    const { outcome, messages } = must(verdicts, ruleKey(rule));
+                    if (rule.kind === "deadlock" &&
+                        outcome === "broken" &&
+                        !drawing &&
+                        !hasSection(spec, "CONSTRAINT", "ACTION_CONSTRAINT"))
+                        deadEnds(graph, rule);
+                    if (outcome !== "broken" || !messages)
+                        continue;
+                    const counterexample = readCounterexample(messages);
+                    if (!drawing ||
+                        lasso(graph, { seq: counterexample, loop: undefined }, spec.variables, find))
+                        addPast(graph, counterexample, spec.variables, rule, past, excludes, find);
+                }
+                const properties = propertiesWith((trace) => lasso(graph, trace, spec.variables, find));
+                return {
+                    ...common,
+                    graph,
+                    paths: undefined,
+                    properties,
+                    drawing,
+                };
+            }
+        }
+        const drawn = pathGraph(spec.variables);
+        const paths = [];
+        for (const rule of rules) {
+            const { outcome, messages } = must(verdicts, ruleKey(rule));
+            if (outcome === "broken" && messages)
+                paths.push(drawn.bug(rule, readCounterexample(messages)));
+        }
+        return {
+            ...common,
+            graph: drawn.graph,
+            paths,
+            properties: propertiesWith(drawn.lasso),
+            drawing: undefined,
+        };
+    }
+    finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}

package/dist/statechart/statechart.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { killGroup, messageOf } from "./run.js";
+const USAGE = `Usage: statechart SPEC.tla [--config FILE] [--view FILE] [--out DIR]
+
+Checks SPEC.tla with TLC and draws its state graph as Mermaid. Above 500 states, the chart
+draws only the paths to the rules that break, and with no rule broken there is no chart.mmd.
+  --config FILE  TLC config. Default: SPEC.cfg beside the spec.
+  --view FILE    A module that exports state(vars) and, if you want, step(action, from, to),
+                 group(vars), colors, and title. state() returns a string for a flat chart, an
+                 array for parent states, or an object for regions. Default: each state's values.
+                 colors gives each group blue, orange, purple, yellow, teal, tan, or pink.
+  --out DIR      Where to write report.md, chart.mmd, tlc.out, and tlc-RULE.out for each
+                 property that breaks and each rule that breaks off the chart. The folder must
+                 be new or empty. Default: SPEC-chart.
+Exit code: TLC's own on the config as written: 0 when every rule holds, 1 when a rule breaks,
+and 2 when TLC stops with an error, a signal kills the check, or the command cannot run. 130 or
+143 when SIGINT or SIGTERM stops the check. Only exits 0 and 1 write output.`;
+let stop;
+const stopped = new Promise((resolve) => {
+    for (const name of ["SIGINT", "SIGTERM"])
+        process.on(name, () => {
+            stop ??= name;
+            resolve();
+        });
+});
+let flags;
+let specFile;
+try {
+    const args = parseArgs({
+        allowPositionals: true,
+        options: { config: { type: "string" }, view: { type: "string" }, out: { type: "string" } },
+    });
+    flags = args.values;
+    [specFile] = args.positionals;
+    if (args.positionals.length !== 1)
+        throw new Error("Give one SPEC.tla.");
+}
+catch (error) {
+    console.error(`${messageOf(error)}\n\n${USAGE}`);
+    process.exit(2);
+}
+const codeOf = (error) => error instanceof Error && "code" in error ? error.code : undefined;
+try {
+    const configFile = flags.config ?? specFile.replace(/\.tla$/, ".cfg");
+    if (!fs.existsSync(configFile))
+        throw new Error(`Cannot find the TLC config ${configFile}. Pass --config FILE.`);
+    const out = flags.out ?? specFile.replace(/\.tla$/, "-chart");
+    let entries = [];
+    let dest;
+    try {
+        entries = fs.readdirSync(out);
+        dest = fs.realpathSync(out);
+    }
+    catch (error) {
+        if (codeOf(error) !== "ENOENT")
+            throw new Error(`${out} cannot be the output folder. ${messageOf(error)}. Pass --out with a new folder.`, { cause: error });
+        if (fs.lstatSync(out, { throwIfNoEntry: false }))
+            throw new Error(`${out} cannot be the output folder. It is a broken link. Pass --out with a new folder.`, { cause: error });
+        dest = path.resolve(out);
+    }
+    if (entries.length)
+        throw new Error(`${out} is not empty. It has ${entries.sort()[0]}. The command writes only to a new or empty folder. Pass --out with a new folder.`);
+    let base = path.dirname(dest);
+    while (!fs.existsSync(base))
+        base = path.dirname(base);
+    const stage = fs.mkdtempSync(path.join(base, `.${path.basename(dest)}.statechart-`));
+    const done = path.join(stage, "done");
+    let tmp;
+    let janitor;
+    let exitCode;
+    try {
+        tmp = fs.mkdtempSync(path.join(os.tmpdir(), "statechart-"));
+        const runtime = process.versions.deno
+            ? [
+                "run",
+                "--quiet",
+                "--no-prompt",
+                "--allow-read",
+                "--allow-write",
+                "--allow-run",
+                "--allow-env",
+            ]
+            : process.execArgv;
+        const worker = spawn(process.execPath, [
+            ...runtime,
+            path.join(import.meta.dirname, "worker.js"),
+            stage,
+            specFile,
+            configFile,
+            ...(flags.view ? [flags.view] : []),
+        ], {
+            detached: true,
+            stdio: ["ignore", "inherit", "inherit"],
+            env: { ...process.env, TMPDIR: tmp },
+        });
+        janitor = spawn("/bin/sh", [
+            "-c",
+            'while read -r line; do :; done; kill -s KILL -- "-$1"; rm -rf -- "$2" "$3"',
+            "sh",
+            String(worker.pid),
+            stage,
+            tmp,
+        ], { detached: true, stdio: ["pipe", "ignore", "ignore"] });
+        const exited = new Promise((resolve) => worker.on("exit", (code) => resolve(code ?? 2)));
+        await Promise.race([stopped, exited]);
+        await killGroup(worker.pid);
+        const verdict = await exited;
+        if (stop) {
+            console.error(`${stop} stopped the check, so the command wrote nothing.`);
+            exitCode = 128 + os.constants.signals[stop];
+        }
+        else if (worker.signalCode) {
+            console.error(`${worker.signalCode} killed the check, so the command wrote nothing.`);
+            exitCode = 2;
+        }
+        else if ((verdict === 0 || verdict === 1) && fs.existsSync(done)) {
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            try {
+                fs.renameSync(done, dest);
+            }
+            catch (error) {
+                if (codeOf(error) !== "ENOTEMPTY" && codeOf(error) !== "EEXIST")
+                    throw error;
+                throw new Error(`${path.join(out, fs.readdirSync(dest).sort()[0])} appeared while the check ran, so the command wrote nothing. Pass --out with a new folder.`, { cause: error });
+            }
+            process.stdout.write(fs.readFileSync(path.join(dest, "report.md")));
+            console.log(`\nWrote ${out}`);
+            exitCode = verdict;
+        }
+        else
+            exitCode = 2;
+    }
+    finally {
+        fs.rmSync(stage, { recursive: true, force: true });
+        if (tmp)
+            fs.rmSync(tmp, { recursive: true, force: true });
+        janitor?.kill("SIGKILL");
+    }
+    process.exit(exitCode);
+}
+catch (error) {
+    console.error(messageOf(error));
+    process.exit(2);
+}

package/dist/statechart/worker.js

@@ -0,0 +1,40 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+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.js";
+import { compile } from "./pipeline.js";
+import { check, messageOf } from "./run.js";
+const [stage, specFile, configFile, viewFile] = process.argv.slice(2);
+try {
+    const view = checkView(viewFile ? await import(__rewriteRelativeImportExtension(pathToFileURL(path.resolve(viewFile)).href, true)) : {}, 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/dist/telemetry/metrics.d.ts

@@ -0,0 +1,13 @@
+import type { WorkflowRecord } from '../runtime/types.js';
+export declare function metrics(workflows: WorkflowRecord[]): {
+    attempts: number;
+    completed: number;
+    verifiedRecorded: number;
+    verificationRate: number | null;
+    tokens: number | null;
+    cost: number | null;
+    blocked: number;
+    staleRecorded: number;
+    elapsedMs: number;
+    interpretation: string;
+};

package/dist/telemetry/metrics.js

@@ -0,0 +1,11 @@
+export function metrics(workflows) {
+    const calls = workflows.flatMap(w => Object.values(w.calls));
+    const complete = calls.filter(c => c.state === 'completed');
+    const verified = complete.filter(c => c.verification?.status === 'passed');
+    const known = calls.filter(c => c.usage?.tokens !== null && c.usage?.tokens !== undefined);
+    const costs = calls.filter(c => c.usage?.cost !== null && c.usage?.cost !== undefined);
+    return { attempts: calls.reduce((n, c) => n + c.attempt, 0), completed: complete.length, verifiedRecorded: verified.length, verificationRate: complete.length ? verified.length / complete.length : null,
+        tokens: known.length === calls.length ? known.reduce((n, c) => n + c.usage.tokens, 0) : null, cost: costs.length === calls.length ? costs.reduce((n, c) => n + c.usage.cost, 0) : null,
+        blocked: calls.filter(c => c.verification?.status === 'blocked').length, staleRecorded: calls.filter(c => c.verification?.status === 'stale').length, elapsedMs: calls.reduce((n, c) => n + (c.usage?.elapsedMs ?? 0), 0),
+        interpretation: 'Recorded gate results; use current artifact checks before delivery. Unknown usage is never counted as zero.' };
+}

package/dist/templates/build.d.ts

@@ -0,0 +1,35 @@
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { WorkflowNodeSpec } from '../runtime/types.js';
+import type { TaskBrief, Budget } from '../contracts/types.js';
+export interface TemplateSpec {
+    kind: 'arena' | 'architect' | 'interrogate' | 'swarm' | 'review' | 'autopilot-stack' | 'autopilot-full';
+    brief: TaskBrief;
+    models?: string[];
+    panel?: string;
+    judgeModel?: string;
+    rubric?: {
+        criterion: string;
+        weight: number;
+    }[];
+    candidateCount?: number;
+    swarmMode?: 'race' | 'partition';
+    slices?: {
+        key: string;
+        task: string;
+        brief: TaskBrief;
+    }[];
+    selectionPolicy?: 'best-of' | 'first-pass' | 'rank-all';
+    judgeMode?: 'cross' | 'per-candidate';
+    independencePolicy?: 'different-model' | 'different-family' | 'explicit-waiver' | 'independent-session';
+    modelFamilies?: Record<string, string>;
+    budget?: Budget;
+}
+/** Configured panels become explicit node models before a workflow is created. */
+export declare function buildTemplate(input: TemplateSpec, ctx?: ExtensionContext): {
+    nodes: WorkflowNodeSpec[];
+    estimatedAgents: number;
+    budget: Budget | undefined;
+    notes: string[];
+    deliveryContract: 'local-dag' | 'candidate-only' | 'remote-stack-required';
+    completionPolicy?: 'first-pass';
+};