velaris-lang 7.1.1 → 8.0.0

package/README.md

@@ -1,71 +1,71 @@
-# velaris-lang
-
-Run code you did not write.
-
-```
-npx velaris-lang script.vel
-```
-
-That program cannot read a file, reach the network or call Python -
-whatever its source says about itself - and a refusal cannot be caught
-and carried past. A run with no `--allow` gets `io` (5.0), so that is
-the default rather than something you have to remember; widen it by
-naming what the program needs, and `--allow all` grants every effect
-and says so on stderr.
-
-```javascript
-import { audit, run } from "velaris-lang";
-
-const report = await audit(source);
-console.log(report.effects);        // ['fs', 'net']
-console.log(report.proven_share);   // 66.7
-
-const result = await run(source, { allow: ["io"] });
-console.log(result.ok, result.output, result.refusedEffect);
-```
-
-Velaris is a language where a function's signature declares its types,
-the effects it may perform, whether it can fail, and promises a theorem
-prover checks before the program runs. This package is a thin wrapper
-around that compiler.
-
-Not a security boundary - allowing `ffi` grants everything Python can
-do. It is a real guard for running a script a model wrote.
-
-## The compiler
-
-The compiler itself is a Python package. This wrapper calls it, so
-install it once:
-
-```
-pip install velaris-lang
-```
-
-Two optional pieces are worth having:
-
-```
-pip install "velaris-lang[full]"
-```
-
-That adds `z3-solver`, which proves a function's promises before the
-program runs instead of leaving them to be checked as it goes, and
-`llvmlite`, which compiles pure integer and float code to native code
-instead of interpreting it. Neither is required. Without them Velaris
-runs fully interpreted and checks promises while running - it prints
-`note: llvmlite is not installed - running fully interpreted` and
-carries on, refusing effects outside the budget exactly the same way.
-
-### Which Python it uses
-
-The wrapper tries `py`, `python` and `python3` on Windows, `python3`
-then `python` elsewhere, asks each one which Velaris it has, and uses
-the newest. If the newest it finds is older than this npm package it
-still uses it, but says so first, on stderr, naming both versions and
-the interpreter - so a stale install left on PATH is visible rather
-than mysterious. If you ask for a subcommand that version does not
-have, it says which command and which version introduced it instead of
-handing it over. `pip install -U velaris-lang` upgrades the compiler.
-
-[Documentation](https://gowrishankar-infra.github.io/velaris-lang/) ·
-[Playground](https://gowrishankar-infra.github.io/velaris-lang/playground.html) ·
-[Source](https://github.com/gowrishankar-infra/velaris-lang)
+# velaris-lang
+
+Run code you did not write.
+
+```
+npx velaris-lang script.vel
+```
+
+That program cannot read a file, reach the network or call Python -
+whatever its source says about itself - and a refusal cannot be caught
+and carried past. A run with no `--allow` gets `io` (5.0), so that is
+the default rather than something you have to remember; widen it by
+naming what the program needs, and `--allow all` grants every effect
+and says so on stderr.
+
+```javascript
+import { audit, run } from "velaris-lang";
+
+const report = await audit(source);
+console.log(report.effects);        // ['fs', 'net']
+console.log(report.proven_share);   // 66.7
+
+const result = await run(source, { allow: ["io"] });
+console.log(result.ok, result.output, result.refusedEffect);
+```
+
+Velaris is a language where a function's signature declares its types,
+the effects it may perform, whether it can fail, and promises a theorem
+prover checks before the program runs. This package is a thin wrapper
+around that compiler.
+
+Not a security boundary - allowing `ffi` grants everything Python can
+do. It is a real guard for running a script a model wrote.
+
+## The compiler
+
+The compiler itself is a Python package. This wrapper calls it, so
+install it once:
+
+```
+pip install velaris-lang
+```
+
+Two optional pieces are worth having:
+
+```
+pip install "velaris-lang[full]"
+```
+
+That adds `z3-solver`, which proves a function's promises before the
+program runs instead of leaving them to be checked as it goes, and
+`llvmlite`, which compiles pure integer and float code to native code
+instead of interpreting it. Neither is required. Without them Velaris
+runs fully interpreted and checks promises while running - it prints
+`note: llvmlite is not installed - running fully interpreted` and
+carries on, refusing effects outside the budget exactly the same way.
+
+### Which Python it uses
+
+The wrapper tries `py`, `python` and `python3` on Windows, `python3`
+then `python` elsewhere, asks each one which Velaris it has, and uses
+the newest. If the newest it finds is older than this npm package it
+still uses it, but says so first, on stderr, naming both versions and
+the interpreter - so a stale install left on PATH is visible rather
+than mysterious. If you ask for a subcommand that version does not
+have, it says which command and which version introduced it instead of
+handing it over. `pip install -U velaris-lang` upgrades the compiler.
+
+[Documentation](https://gowrishankar-infra.github.io/velaris-lang/) ·
+[Playground](https://gowrishankar-infra.github.io/velaris-lang/playground.html) ·
+[Source](https://github.com/gowrishankar-infra/velaris-lang)

package/bin/velaris.js

@@ -1,111 +1,111 @@
-#!/usr/bin/env node
-// npx velaris hello.vel            (it gets io; --allow to widen)
-//
-// Velaris's compiler is one Python file. This hands your arguments to
-// it, and if it is not installed, says exactly how to fix that rather
-// than failing with a confusing spawn error.
-//
-// It also says when the compiler it found is older than this package.
-// Two things can go wrong quietly otherwise: a stale Velaris earlier in
-// PATH shadows a newer one, and a subcommand added after that stale
-// version came out is read by the old compiler as a file name, so
-// `npx velaris-lang mcp` fails with "cannot find file 'mcp'".
-
-import { spawn } from "node:child_process";
-import {
-  behindWarning,
-  compareVersions,
-  findVelaris,
-  NOT_INSTALLED,
-  packageVersion,
-} from "../python.js";
-
-// The version each subcommand first shipped in, from the changelog. It
-// is what lets this wrapper name a missing command instead of leaving
-// the old compiler to mistake it for a file. check_library.py holds it
-// to the compiler's own dispatch, so a new subcommand cannot be added
-// without an entry here.
-const INTRODUCED = {
-  repl: "1.9",
-  run: "1.9",
-  version: "1.9",
-  fmt: "1.10",
-  lsp: "1.11",
-  doctor: "2.2",
-  new: "2.2",
-  explain: "2.6",
-  proofs: "2.6",
-  check: "2.7",
-  test: "2.17",
-  trace: "2.21",
-  add: "2.23",
-  deps: "2.23",
-  verify: "2.23",
-  build: "2.28",
-  clean: "2.29",
-  audit: "2.41.1",
-  card: "2.41.1",
-  "mcp-install": "2.53",
-  serve: "2.54",
-  "mcp-manifest": "3.4.0",
-  "mcp-verify": "3.4.0",
-  capabilities: "4.0.0",
-  review: "4.0.0",
-  conformance: "4.1.0",
-  attest: "4.2.0",
-  mcp: "4.3.3",
-  migrate: "5.0.0",
-  "deps-diff": "7.1.0",
-};
-
-// The two flags the compiler takes before any command, each with a
-// value of its own; everything else beginning with "-" is a flag whose
-// value, if it has one, is attached. What is left is the subcommand,
-// or a file name - which is not in the table, so it is left alone.
-const GLOBAL_WITH_VALUE = ["--proof-timeout", "--max-memory-mb"];
-
-function requestedCommand(args) {
-  for (let i = 0; i < args.length; i++) {
-    if (GLOBAL_WITH_VALUE.includes(args[i])) {
-      i++;
-      continue;
-    }
-    if (args[i].startsWith("-")) continue;
-    return args[i];
-  }
-  return null;
-}
-
-const args = process.argv.slice(2);
-const ours = packageVersion();
-const found = findVelaris();
-
-if (!found) {
-  console.error(NOT_INSTALLED);
-  process.exit(127);
-}
-
-const wanted = requestedCommand(args);
-const needs = wanted ? INTRODUCED[wanted] : null;
-if (needs && found.version && compareVersions(found.version, needs) < 0) {
-  console.error(
-    `velaris ${wanted} arrived in Velaris ${needs}; the compiler at ` +
-      `${found.interpreter} is ${found.version}` +
-      (ours ? `, while this npm package is ${ours}` : "") +
-      ". Upgrade the compiler with: pip install -U velaris-lang"
-  );
-  process.exit(127);
-}
-
-const behind = behindWarning(found, ours);
-if (behind) console.error(behind);
-
-// The interpreter, not the name that found it: the version answer came
-// from that executable, so that executable is the one to run.
-const child = spawn(found.interpreter, ["-m", "velaris", ...args], {
-  stdio: "inherit",
-});
-child.on("exit", (code, signal) => {
-  if (signal) process.kill(process.pid, signal);
-  else process.exit(code ?? 0);
-});
+#!/usr/bin/env node
+// npx velaris hello.vel            (it gets io; --allow to widen)
+//
+// Velaris's compiler is one Python file. This hands your arguments to
+// it, and if it is not installed, says exactly how to fix that rather
+// than failing with a confusing spawn error.
+//
+// It also says when the compiler it found is older than this package.
+// Two things can go wrong quietly otherwise: a stale Velaris earlier in
+// PATH shadows a newer one, and a subcommand added after that stale
+// version came out is read by the old compiler as a file name, so
+// `npx velaris-lang mcp` fails with "cannot find file 'mcp'".
+
+import { spawn } from "node:child_process";
+import {
+  behindWarning,
+  compareVersions,
+  findVelaris,
+  NOT_INSTALLED,
+  packageVersion,
+} from "../python.js";
+
+// The version each subcommand first shipped in, from the changelog. It
+// is what lets this wrapper name a missing command instead of leaving
+// the old compiler to mistake it for a file. check_library.py holds it
+// to the compiler's own dispatch, so a new subcommand cannot be added
+// without an entry here.
+const INTRODUCED = {
+  repl: "1.9",
+  run: "1.9",
+  version: "1.9",
+  fmt: "1.10",
+  lsp: "1.11",
+  doctor: "2.2",
+  new: "2.2",
+  explain: "2.6",
+  proofs: "2.6",
+  check: "2.7",
+  test: "2.17",
+  trace: "2.21",
+  add: "2.23",
+  deps: "2.23",
+  verify: "2.23",
+  build: "2.28",
+  clean: "2.29",
+  audit: "2.41.1",
+  card: "2.41.1",
+  "mcp-install": "2.53",
+  serve: "2.54",
+  "mcp-manifest": "3.4.0",
+  "mcp-verify": "3.4.0",
+  capabilities: "4.0.0",
+  review: "4.0.0",
+  conformance: "4.1.0",
+  attest: "4.2.0",
+  mcp: "4.3.3",
+  migrate: "5.0.0",
+  "deps-diff": "7.1.0",
+};
+
+// The two flags the compiler takes before any command, each with a
+// value of its own; everything else beginning with "-" is a flag whose
+// value, if it has one, is attached. What is left is the subcommand,
+// or a file name - which is not in the table, so it is left alone.
+const GLOBAL_WITH_VALUE = ["--proof-timeout", "--max-memory-mb"];
+
+function requestedCommand(args) {
+  for (let i = 0; i < args.length; i++) {
+    if (GLOBAL_WITH_VALUE.includes(args[i])) {
+      i++;
+      continue;
+    }
+    if (args[i].startsWith("-")) continue;
+    return args[i];
+  }
+  return null;
+}
+
+const args = process.argv.slice(2);
+const ours = packageVersion();
+const found = findVelaris();
+
+if (!found) {
+  console.error(NOT_INSTALLED);
+  process.exit(127);
+}
+
+const wanted = requestedCommand(args);
+const needs = wanted ? INTRODUCED[wanted] : null;
+if (needs && found.version && compareVersions(found.version, needs) < 0) {
+  console.error(
+    `velaris ${wanted} arrived in Velaris ${needs}; the compiler at ` +
+      `${found.interpreter} is ${found.version}` +
+      (ours ? `, while this npm package is ${ours}` : "") +
+      ". Upgrade the compiler with: pip install -U velaris-lang"
+  );
+  process.exit(127);
+}
+
+const behind = behindWarning(found, ours);
+if (behind) console.error(behind);
+
+// The interpreter, not the name that found it: the version answer came
+// from that executable, so that executable is the one to run.
+const child = spawn(found.interpreter, ["-m", "velaris", ...args], {
+  stdio: "inherit",
+});
+child.on("exit", (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 0);
+});

package/index.js

@@ -1,127 +1,127 @@
-// Velaris from Node: check what a program does, audit what it may
-// touch, and run it under an effect budget.
-//
-//   import { check, audit, run } from "velaris-lang";
-//
-//   const report = await audit(source);
-//   console.log(report.effects);              // ['fs', 'net']
-//
-//   const result = await run(source, { allow: ["io"] });
-//   console.log(result.ok, result.output, result.refusedEffect);
-//
-// Every call goes to the same compiler the command line uses, so the
-// guarantees are the same: an effect outside the budget is refused
-// while the program runs, whatever its source claims, and a refusal
-// cannot be caught by the program.
-
-import { spawn } from "node:child_process";
-import { behindWarning, findVelaris, packageVersion } from "./python.js";
-
-let cachedPython = null;
-
-// Said once per process, not once per call: several calls through one
-// stale compiler are one mistake, and repeating it would bury whatever
-// the caller was printing.
-let saidBehind = false;
-
-// Not the first Python that can import velaris - the one with the
-// newest velaris. Taking the first let an old install earlier in PATH
-// shadow a newer one, which then answered every call in this module
-// with the behaviour of a version the caller did not ask for.
-function findPython() {
-  if (cachedPython) return cachedPython;
-  const found = findVelaris();
-  if (!found) {
-    throw new Error("velaris is not installed: pip install velaris-lang");
-  }
-  if (!saidBehind) {
-    const behind = behindWarning(found, packageVersion());
-    if (behind) console.error(behind);
-    saidBehind = true;
-  }
-  return (cachedPython = found.interpreter);
-}
-
-function callPython(script, payload) {
-  const exe = findPython();
-  return new Promise((resolve, reject) => {
-    const child = spawn(exe, ["-c", script], {
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-    let out = "";
-    let err = "";
-    child.stdout.on("data", (d) => (out += d));
-    child.stderr.on("data", (d) => (err += d));
-    child.on("error", reject);
-    child.on("close", () => {
-      try {
-        resolve(JSON.parse(out));
-      } catch {
-        reject(new Error(err.trim() || "velaris gave no answer"));
-      }
-    });
-    child.stdin.end(JSON.stringify(payload));
-  });
-}
-
-const BRIDGE = `
-import json, sys
-import velaris
-ask = json.load(sys.stdin)
-what = ask["what"]
-source = ask["source"]
-if what == "check":
-    print(json.dumps(velaris.check(source).as_dict()))
-elif what == "audit":
-    print(json.dumps(velaris.audit(source).as_dict()))
-elif what == "card":
-    print(json.dumps({"card": velaris.card()}))
-else:
-    out = velaris.run(source, allow=set(ask.get("allow") or ["io"]),
-                      stdin=ask.get("stdin", ""),
-                      args=ask.get("args") or [])
-    print(json.dumps(out.as_dict()))
-`;
-
-/** Compile without running. Problems, and what was proven. */
-export async function check(source) {
-  return callPython(BRIDGE, { what: "check", source });
-}
-
-/** What a program can touch, promise and fail at - before running. */
-export async function audit(source) {
-  return callPython(BRIDGE, { what: "audit", source });
-}
-
-/** The language, small enough to paste into a model. */
-export async function card() {
-  const answer = await callPython(BRIDGE, { what: "card", source: "x" });
-  return answer.card;
-}
-
-/**
- * Run under an effect budget.
- *
- * allow: ["io"] means it cannot read files, reach the network, call
- * Python, ask the clock or use randomness - whatever the source says.
- * Not a security boundary: allowing "ffi" grants everything Python can.
- */
-export async function run(source, options = {}) {
-  const answer = await callPython(BRIDGE, {
-    what: "run",
-    source,
-    allow: options.allow ?? ["io"],
-    stdin: options.stdin ?? "",
-    args: options.args ?? [],
-  });
-  return {
-    ok: answer.ok,
-    output: answer.output,
-    logs: answer.logs,
-    problems: answer.problems,
-    refusedEffect: answer.refused_effect,
-    exitCode: answer.exit_code,
-  };
-}
-
-export default { check, audit, run, card };
+// Velaris from Node: check what a program does, audit what it may
+// touch, and run it under an effect budget.
+//
+//   import { check, audit, run } from "velaris-lang";
+//
+//   const report = await audit(source);
+//   console.log(report.effects);              // ['fs', 'net']
+//
+//   const result = await run(source, { allow: ["io"] });
+//   console.log(result.ok, result.output, result.refusedEffect);
+//
+// Every call goes to the same compiler the command line uses, so the
+// guarantees are the same: an effect outside the budget is refused
+// while the program runs, whatever its source claims, and a refusal
+// cannot be caught by the program.
+
+import { spawn } from "node:child_process";
+import { behindWarning, findVelaris, packageVersion } from "./python.js";
+
+let cachedPython = null;
+
+// Said once per process, not once per call: several calls through one
+// stale compiler are one mistake, and repeating it would bury whatever
+// the caller was printing.
+let saidBehind = false;
+
+// Not the first Python that can import velaris - the one with the
+// newest velaris. Taking the first let an old install earlier in PATH
+// shadow a newer one, which then answered every call in this module
+// with the behaviour of a version the caller did not ask for.
+function findPython() {
+  if (cachedPython) return cachedPython;
+  const found = findVelaris();
+  if (!found) {
+    throw new Error("velaris is not installed: pip install velaris-lang");
+  }
+  if (!saidBehind) {
+    const behind = behindWarning(found, packageVersion());
+    if (behind) console.error(behind);
+    saidBehind = true;
+  }
+  return (cachedPython = found.interpreter);
+}
+
+function callPython(script, payload) {
+  const exe = findPython();
+  return new Promise((resolve, reject) => {
+    const child = spawn(exe, ["-c", script], {
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (err += d));
+    child.on("error", reject);
+    child.on("close", () => {
+      try {
+        resolve(JSON.parse(out));
+      } catch {
+        reject(new Error(err.trim() || "velaris gave no answer"));
+      }
+    });
+    child.stdin.end(JSON.stringify(payload));
+  });
+}
+
+const BRIDGE = `
+import json, sys
+import velaris
+ask = json.load(sys.stdin)
+what = ask["what"]
+source = ask["source"]
+if what == "check":
+    print(json.dumps(velaris.check(source).as_dict()))
+elif what == "audit":
+    print(json.dumps(velaris.audit(source).as_dict()))
+elif what == "card":
+    print(json.dumps({"card": velaris.card()}))
+else:
+    out = velaris.run(source, allow=set(ask.get("allow") or ["io"]),
+                      stdin=ask.get("stdin", ""),
+                      args=ask.get("args") or [])
+    print(json.dumps(out.as_dict()))
+`;
+
+/** Compile without running. Problems, and what was proven. */
+export async function check(source) {
+  return callPython(BRIDGE, { what: "check", source });
+}
+
+/** What a program can touch, promise and fail at - before running. */
+export async function audit(source) {
+  return callPython(BRIDGE, { what: "audit", source });
+}
+
+/** The language, small enough to paste into a model. */
+export async function card() {
+  const answer = await callPython(BRIDGE, { what: "card", source: "x" });
+  return answer.card;
+}
+
+/**
+ * Run under an effect budget.
+ *
+ * allow: ["io"] means it cannot read files, reach the network, call
+ * Python, ask the clock or use randomness - whatever the source says.
+ * Not a security boundary: allowing "ffi" grants everything Python can.
+ */
+export async function run(source, options = {}) {
+  const answer = await callPython(BRIDGE, {
+    what: "run",
+    source,
+    allow: options.allow ?? ["io"],
+    stdin: options.stdin ?? "",
+    args: options.args ?? [],
+  });
+  return {
+    ok: answer.ok,
+    output: answer.output,
+    logs: answer.logs,
+    problems: answer.problems,
+    refusedEffect: answer.refused_effect,
+    exitCode: answer.exit_code,
+  };
+}
+
+export default { check, audit, run, card };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "velaris-lang",
-  "version": "7.1.1",
+  "version": "8.0.0",
   "mcpName": "io.github.gowrishankar-infra/velaris",
   "description": "Run code you did not write. A language where a signature declares its effects and promises, and the runtime refuses anything you did not allow.",
   "keywords": [

package/python.js

@@ -1,143 +1,143 @@
-// Finding the Python that holds the Velaris compiler.
-//
-// The npm package is a wrapper, not a copy: it finds a Python that can
-// import `velaris` and calls it. Until 4.3.4 it took the first Python
-// that could import the module at all, which meant an old Velaris in an
-// early candidate silently shadowed a newer one further down - and a
-// subcommand added after that old version came out looked to the user
-// like a missing file rather than a missing compiler.
-//
-// So: ask every candidate which version it has, and take the newest.
-// The caller decides what to say when the newest is still older than
-// the package that invoked it; what this module promises is that the
-// choice is made on version and that the version is known.
-
-import { spawnSync } from "node:child_process";
-import { readFileSync } from "node:fs";
-
-// One line of JSON on stdout: the version the module declares, and the
-// interpreter it came from. `velaris.VERSION` has been there since 1.0,
-// so every real Velaris answers; something importable as `velaris` that
-// is not one is reported as a null version rather than as no Velaris at
-// all, and ranks below everything that can say what it is.
-const PROBE =
-  "import json,sys,velaris;" +
-  "sys.stdout.write(json.dumps({" +
-  '"version": getattr(velaris, "VERSION", None), ' +
-  '"interpreter": sys.executable}))';
-
-export function candidates() {
-  return process.platform === "win32"
-    ? ["py", "python", "python3"]
-    : ["python3", "python"];
-}
-
-/** -1, 0 or 1, comparing dotted numeric versions of any length. */
-export function compareVersions(a, b) {
-  const parts = (v) =>
-    String(v)
-      .split(".")
-      .map((n) => {
-        const x = parseInt(n, 10);
-        return Number.isFinite(x) ? x : 0;
-      });
-  const pa = parts(a);
-  const pb = parts(b);
-  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-    const x = pa[i] ?? 0;
-    const y = pb[i] ?? 0;
-    if (x !== y) return x < y ? -1 : 1;
-  }
-  return 0;
-}
-
-// A version we could not read loses to every version we could, so an
-// unreadable one is never preferred over a known one.
-function newer(a, b) {
-  if (a === null) return false;
-  if (b === null) return true;
-  return compareVersions(a, b) > 0;
-}
-
-/**
- * The candidate holding the newest Velaris.
- *
- * Returns null if no candidate has it at all, else { command,
- * interpreter, version, all }: `version` is null when the module
- * declares none, and `all` is every candidate that had Velaris, in the
- * order they were tried.
- */
-export function findVelaris() {
-  const found = [];
-  const seen = new Set();
-  for (const command of candidates()) {
-    const probe = spawnSync(command, ["-c", PROBE], { encoding: "utf8" });
-    if (probe.error || probe.status !== 0) continue;
-    let answer;
-    try {
-      const lines = (probe.stdout || "").trim().split(/\r?\n/).filter(Boolean);
-      answer = JSON.parse(lines[lines.length - 1]);
-    } catch {
-      continue; // it imported but would not say what it is
-    }
-    const version =
-      typeof answer.version === "string" && /^\d+(\.\d+)*$/.test(answer.version)
-        ? answer.version
-        : null;
-    const interpreter = answer.interpreter || command;
-    // `py` and `python` are often the same interpreter; count it once
-    // so that "the newest of several" is about several Pythons.
-    if (seen.has(interpreter)) continue;
-    seen.add(interpreter);
-    found.push({ command, interpreter, version });
-  }
-  if (found.length === 0) return null;
-  let best = found[0];
-  for (const one of found.slice(1)) {
-    if (newer(one.version, best.version)) best = one;
-  }
-  return { ...best, all: found };
-}
-
-/**
- * The version of the npm package this file belongs to, or null.
- *
- * Resolved against this file, which sits beside package.json, so it is
- * the same answer wherever it is called from.
- */
-export function packageVersion() {
-  try {
-    const beside = new URL("./package.json", import.meta.url);
-    return JSON.parse(readFileSync(beside, "utf8")).version || null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * One line for stderr when the compiler is older than the package that
- * invoked it, or null when it is not. Never silence: a wrapper running
- * a compiler older than itself is the one thing the user cannot see.
- */
-export function behindWarning(found, ours) {
-  if (!ours) return null;
-  if (found.version === null) {
-    return (
-      `velaris-lang ${ours} (npm) is using a Velaris at ${found.interpreter} ` +
-      "that does not say which version it is; upgrade it with: " +
-      "pip install -U velaris-lang"
-    );
-  }
-  if (compareVersions(found.version, ours) >= 0) return null;
-  return (
-    `velaris-lang ${ours} (npm) is using Velaris ${found.version}, from ` +
-    `${found.interpreter}; upgrade the compiler with: ` +
-    "pip install -U velaris-lang"
-  );
-}
-
-export const NOT_INSTALLED =
-  "Velaris needs its compiler, which is a Python package:\n" +
-  "\n    pip install velaris-lang\n" +
-  "\nOr try it with nothing installed:\n" +
-  "    https://gowrishankar-infra.github.io/velaris-lang/playground.html";
+// Finding the Python that holds the Velaris compiler.
+//
+// The npm package is a wrapper, not a copy: it finds a Python that can
+// import `velaris` and calls it. Until 4.3.4 it took the first Python
+// that could import the module at all, which meant an old Velaris in an
+// early candidate silently shadowed a newer one further down - and a
+// subcommand added after that old version came out looked to the user
+// like a missing file rather than a missing compiler.
+//
+// So: ask every candidate which version it has, and take the newest.
+// The caller decides what to say when the newest is still older than
+// the package that invoked it; what this module promises is that the
+// choice is made on version and that the version is known.
+
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+// One line of JSON on stdout: the version the module declares, and the
+// interpreter it came from. `velaris.VERSION` has been there since 1.0,
+// so every real Velaris answers; something importable as `velaris` that
+// is not one is reported as a null version rather than as no Velaris at
+// all, and ranks below everything that can say what it is.
+const PROBE =
+  "import json,sys,velaris;" +
+  "sys.stdout.write(json.dumps({" +
+  '"version": getattr(velaris, "VERSION", None), ' +
+  '"interpreter": sys.executable}))';
+
+export function candidates() {
+  return process.platform === "win32"
+    ? ["py", "python", "python3"]
+    : ["python3", "python"];
+}
+
+/** -1, 0 or 1, comparing dotted numeric versions of any length. */
+export function compareVersions(a, b) {
+  const parts = (v) =>
+    String(v)
+      .split(".")
+      .map((n) => {
+        const x = parseInt(n, 10);
+        return Number.isFinite(x) ? x : 0;
+      });
+  const pa = parts(a);
+  const pb = parts(b);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const x = pa[i] ?? 0;
+    const y = pb[i] ?? 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+// A version we could not read loses to every version we could, so an
+// unreadable one is never preferred over a known one.
+function newer(a, b) {
+  if (a === null) return false;
+  if (b === null) return true;
+  return compareVersions(a, b) > 0;
+}
+
+/**
+ * The candidate holding the newest Velaris.
+ *
+ * Returns null if no candidate has it at all, else { command,
+ * interpreter, version, all }: `version` is null when the module
+ * declares none, and `all` is every candidate that had Velaris, in the
+ * order they were tried.
+ */
+export function findVelaris() {
+  const found = [];
+  const seen = new Set();
+  for (const command of candidates()) {
+    const probe = spawnSync(command, ["-c", PROBE], { encoding: "utf8" });
+    if (probe.error || probe.status !== 0) continue;
+    let answer;
+    try {
+      const lines = (probe.stdout || "").trim().split(/\r?\n/).filter(Boolean);
+      answer = JSON.parse(lines[lines.length - 1]);
+    } catch {
+      continue; // it imported but would not say what it is
+    }
+    const version =
+      typeof answer.version === "string" && /^\d+(\.\d+)*$/.test(answer.version)
+        ? answer.version
+        : null;
+    const interpreter = answer.interpreter || command;
+    // `py` and `python` are often the same interpreter; count it once
+    // so that "the newest of several" is about several Pythons.
+    if (seen.has(interpreter)) continue;
+    seen.add(interpreter);
+    found.push({ command, interpreter, version });
+  }
+  if (found.length === 0) return null;
+  let best = found[0];
+  for (const one of found.slice(1)) {
+    if (newer(one.version, best.version)) best = one;
+  }
+  return { ...best, all: found };
+}
+
+/**
+ * The version of the npm package this file belongs to, or null.
+ *
+ * Resolved against this file, which sits beside package.json, so it is
+ * the same answer wherever it is called from.
+ */
+export function packageVersion() {
+  try {
+    const beside = new URL("./package.json", import.meta.url);
+    return JSON.parse(readFileSync(beside, "utf8")).version || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One line for stderr when the compiler is older than the package that
+ * invoked it, or null when it is not. Never silence: a wrapper running
+ * a compiler older than itself is the one thing the user cannot see.
+ */
+export function behindWarning(found, ours) {
+  if (!ours) return null;
+  if (found.version === null) {
+    return (
+      `velaris-lang ${ours} (npm) is using a Velaris at ${found.interpreter} ` +
+      "that does not say which version it is; upgrade it with: " +
+      "pip install -U velaris-lang"
+    );
+  }
+  if (compareVersions(found.version, ours) >= 0) return null;
+  return (
+    `velaris-lang ${ours} (npm) is using Velaris ${found.version}, from ` +
+    `${found.interpreter}; upgrade the compiler with: ` +
+    "pip install -U velaris-lang"
+  );
+}
+
+export const NOT_INSTALLED =
+  "Velaris needs its compiler, which is a Python package:\n" +
+  "\n    pip install velaris-lang\n" +
+  "\nOr try it with nothing installed:\n" +
+  "    https://gowrishankar-infra.github.io/velaris-lang/playground.html";