lemmascript 0.5.11 → 0.5.13

package/README.md

@@ -45,7 +45,7 @@ See the external case studies:
 **Install from npm:**
 
 ```sh
-npm install lemmascript
+npm install -g lemmascript
 ```
 
 **Or from source:**
@@ -67,17 +67,21 @@ git clone https://github.com/namin/velvet.git -b lemma ../velvet
 ### Dafny backend
 
 ```sh
-npx lsc gen --backend=dafny src/myModule.ts
-npx lsc check --backend=dafny src/myModule.ts
-npx lsc regen --backend=dafny src/myModule.ts
+lsc gen --backend=dafny src/myModule.ts
+lsc check --backend=dafny src/myModule.ts
+lsc regen --backend=dafny src/myModule.ts
 ```
 
+With no file argument, `lsc check` batches over `LemmaScript-files.txt` (one `filepath [timeout] [extra dafny flags…]` per line — the list `tools/check.sh` runs in CI).
+
+From a sibling source checkout, the equivalent of `lsc` is `npx tsx ../LemmaScript/tools/src/lsc.ts` — no build step, toolchain edits apply immediately.
+
 The Dafny backend generates two files per TS source: `foo.dfy.gen` (always regeneratable) and `foo.dfy` (source of truth, with LLM/user proof additions). The diff between them must be additions-only.
 
 ### Lean backend
 
 ```sh
-npx lsc gen --backend=lean src/myModule.ts
+lsc gen --backend=lean src/myModule.ts
 lake build
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lemmascript",
-  "version": "0.5.11",
+  "version": "0.5.13",
   "description": "A verification toolchain for TypeScript — generates Lean 4 or Dafny from annotated TS",
   "type": "module",
   "engines": {

package/tools/dist/dafny-commands.js

@@ -60,11 +60,14 @@ export function dafnyVerify(dfyPath, dir, timeLimit, extraFlags) {
         execFileSync("dafny", args, { cwd: dir, stdio: "inherit" });
         return true;
     }
-    catch {
+    catch (e) {
+        if (e?.code === "ENOENT") {
+            console.error("ERROR: `dafny` not found on PATH — verification never ran. Install Dafny 4.x: https://dafny.org/");
+        }
         return false;
     }
 }
-export function dafnyRegen(genPath, dfyPath, basePath, text, dir) {
+export function dafnyRegen(genPath, dfyPath, basePath, text, dir, timeLimit, extraFlags) {
     // 1. Read old gen before overwriting (needed for base seeding)
     const oldGen = existsSync(genPath) ? readFileSync(genPath, "utf-8") : "";
     // 2. Always write new gen so user can inspect latest output
@@ -73,7 +76,7 @@ export function dafnyRegen(genPath, dfyPath, basePath, text, dir) {
     if (!existsSync(dfyPath)) {
         writeFileSync(dfyPath, text);
         console.log(`Created: ${path.basename(dfyPath)}`);
-        if (!dafnyVerify(dfyPath, dir)) {
+        if (!dafnyVerify(dfyPath, dir, timeLimit, extraFlags)) {
             console.error(`FAILED: ${path.basename(dfyPath)} verification failed on first run.`);
             process.exit(1);
         }
@@ -108,7 +111,7 @@ export function dafnyRegen(genPath, dfyPath, basePath, text, dir) {
         process.exit(1);
     }
     // 7. Verify
-    if (!dafnyVerify(dfyPath, dir)) {
+    if (!dafnyVerify(dfyPath, dir, timeLimit, extraFlags)) {
         console.error(`FAILED: ${path.basename(dfyPath)} verification failed.`);
         process.exit(1);
     }

package/tools/dist/dafny-emit.js

@@ -1,6 +1,31 @@
 /**
  * Dafny emitter — IR → Dafny text.
  */
+import { usesName, usesNameInDecl } from "./ir.js";
+import { freshName } from "./names.js";
+import { renameFreeVar } from "./transform.js";
+/** Fresh binder for a comprehension wrapping the given subexpressions: `base`
+ *  verbatim unless one of them references it, then primed until free. A *local*
+ *  check — a same-named name elsewhere in the module keeps the plain binder. */
+function freshBinder(base, ...wrapped) {
+    return freshName(base, name => wrapped.some(w => usesName(w, name)));
+}
+/** Binder + body for lowering a single-return lambda to a comprehension whose
+ *  receiver is emitted inside the binder's scope. TS scoping keeps the receiver
+ *  outside the lambda, so a lambda param sharing a name with anything free in
+ *  the receiver would capture it — e.g. `mk(n).some(n => …)` naively emitting
+ *  `exists n :: n in mk(n) && …`. Alpha-rename the param out of the way (and
+ *  its free uses in the body); the zero-param default must also dodge free
+ *  names in the body. */
+function comprehensionBinder(lam, value, receiver) {
+    const rawName = lam.params[0]?.name;
+    if (rawName === undefined)
+        return { binder: escapeName(freshBinder("x", receiver, value)), body: value };
+    if (!usesName(receiver, rawName))
+        return { binder: escapeName(rawName), body: value };
+    const fresh = freshBinder(rawName, receiver, value);
+    return { binder: escapeName(fresh), body: renameFreeVar(value, rawName, fresh) };
+}
 // ── Ty → Dafny type string ─────────────────────────────────
 function tyToDafny(ty) {
     switch (ty.kind) {
@@ -59,12 +84,19 @@ function escapeName(name) {
     // as the current method's out-parameter name.
     if (name === "\\result")
         return _resultName;
+    let out = name;
     if (DAFNY_KEYWORDS.has(name))
-        return `${name}_`;
+        out = `${name}_`;
     // Dafny doesn't allow identifiers starting with _
-    if (name.startsWith("_"))
-        return `i${name}`;
-    return name;
+    else if (name.startsWith("_"))
+        out = `i${name}`;
+    else
+        return name;
+    // Mangling must stay injective: the mangled form may itself be a name the
+    // user wrote (`match` → `match_` beside a real `match_`, `_x` → `i_x` beside
+    // a real `i_x`), silently merging two distinct variables. `freshName` primes
+    // it clear of user-name space (a prime can't occur in a TS identifier).
+    return freshName(out);
 }
 /** Format a typed parameter list for Dafny: "x: int, y: seq<int>" */
 function paramList(params) {
@@ -73,17 +105,18 @@ function paramList(params) {
 /** Format a method signature header, omitting `returns` for void methods.
  *  Dafny's definite-assignment rule rejects unassigned out-parameters, so a
  *  `returns (res: ())` on a void method fails verification. */
-function methodHeader(prefix, params, returnType) {
+function methodHeader(prefix, params, returnType, scope) {
     const sig = `${prefix}(${paramList(params)})`;
     if (returnType.kind === "void")
         return sig;
-    // The out-parameter is `res` by default, but a parameter named `res` (e.g. an
-    // Express handler's `(req, res)`) would collide; pick a fresh name and record
-    // it so `\result` references in the ensures/body resolve to the same name.
-    const taken = new Set(params.map(p => escapeName(p.name)));
-    let resName = "res";
-    while (taken.has(resName))
-        resName += "_";
+    // The out-parameter is `res` by default, but a param (an Express handler's
+    // `(req, res)`), body local, or callee named `res` would shadow it. Check only
+    // *this method's own* signature and body — `res` is common module-wide (fields,
+    // unrelated params), so a module-wide check would prime spuriously. The primed
+    // name is recorded so `\result` references resolve to it.
+    const taken = (n) => params.some(p => escapeName(p.name) === n) ||
+        (scope !== undefined && usesNameInDecl(scope.requires, scope.ensures, scope.body, n));
+    const resName = freshName("res", taken);
     _resultName = resName;
     return `${sig} returns (${resName}: ${tyToDafny(returnType)})`;
 }
@@ -222,8 +255,8 @@ function emitExpr(e) {
                     const ret = lam.body[0];
                     if (ret.kind !== "return")
                         throw new Error("unreachable");
-                    const p = escapeName(lam.params[0]?.name ?? "x");
-                    const body = emitExpr(ret.value);
+                    const { binder: p, body: v } = comprehensionBinder(lam, ret.value, e.obj);
+                    const body = emitExpr(v);
                     return `(exists ${p} :: ${p} in ${obj} && ${body})`;
                 }
             }
@@ -300,8 +333,13 @@ function emitExpr(e) {
                     return `${obj}[${args[0]} := ${args[1]}]`;
                 if (e.method === "has")
                     return `(${args[0]} in ${obj})`;
-                if (e.method === "delete")
-                    return `(map k | k in ${obj} && k != ${args[0]} :: ${obj}[k])`;
+                if (e.method === "delete") {
+                    // Minted comprehension binder: freshen so a user variable `k` in the
+                    // receiver or key isn't captured (`k != k` would delete nothing).
+                    // Local check — only this comprehension's own operands can collide.
+                    const k = freshBinder("k", e.obj, e.args[0]);
+                    return `(map ${k} | ${k} in ${obj} && ${k} != ${args[0]} :: ${obj}[${k}])`;
+                }
             }
             // Set methods
             if (ty === "set") {
@@ -321,8 +359,8 @@ function emitExpr(e) {
                     const ret = lam.body[0];
                     if (ret.kind !== "return")
                         throw new Error("unreachable");
-                    const p = escapeName(lam.params[0]?.name ?? "x");
-                    const body = emitExpr(ret.value);
+                    const { binder: p, body: v } = comprehensionBinder(lam, ret.value, e.obj);
+                    const body = emitExpr(v);
                     return `(set ${p} | ${p} in ${obj} && ${body})`;
                 }
             }
@@ -736,7 +774,7 @@ function emitDecl(d) {
         }
         case "method": {
             const tp = d.typeParams.length > 0 ? `<${d.typeParams.join(", ")}>` : "";
-            const lines = [methodHeader(`method ${d.name}${tp}`, d.params, d.returnType)];
+            const lines = [methodHeader(`method ${d.name}${tp}`, d.params, d.returnType, d)];
             for (const r of d.requires)
                 lines.push(`  requires ${emitExpr(r)}`);
             for (const e of d.ensures)
@@ -756,7 +794,7 @@ function emitDecl(d) {
             if (d.fields.length > 0 && d.methods.length > 0)
                 lines.push("");
             for (const m of d.methods) {
-                lines.push(`  ${methodHeader(`method ${m.name}`, m.params, m.returnType)}`);
+                lines.push(`  ${methodHeader(`method ${m.name}`, m.params, m.returnType, m)}`);
                 for (const r of m.requires)
                     lines.push(`    requires ${emitExpr(r)}`);
                 for (const e of m.ensures)

package/tools/dist/extract.js

@@ -6,6 +6,7 @@
  */
 import { Project, Node, SyntaxKind, ScriptTarget, ts } from "ts-morph";
 import { initTypeParser } from "./types.js";
+import { setUserNames, freshName } from "./names.js";
 // ── Expression extraction ────────────────────────────────────
 /** When set, calls whose function/method name matches this key are replaced with havoc. */
 let _havocKey = null;
@@ -1215,7 +1216,7 @@ function extractStmts(stmts) {
                         let initExpr = extractExpr(initializer);
                         let initVar = initExpr;
                         if (initExpr.kind !== "var") {
-                            const tempName = `_destr${_destrCounter++}`;
+                            const tempName = freshName(`_destr${_destrCounter++}`);
                             const initTs = _eraseGenerics(typeToString(initializer.getType()));
                             result.push({ kind: "let", name: tempName, mutable: false, tsType: initTs, init: initExpr, line });
                             initVar = { kind: "var", name: tempName };
@@ -1259,7 +1260,7 @@ function extractStmts(stmts) {
                             let initExpr = extractExpr(initializer);
                             let initVar = initExpr;
                             if (initExpr.kind !== "var") {
-                                const tempName = `_destr${_destrCounter++}`;
+                                const tempName = freshName(`_destr${_destrCounter++}`);
                                 const initTs = _eraseGenerics(typeToString(initializer.getType()));
                                 result.push({ kind: "let", name: tempName, mutable: false, tsType: initTs, init: initExpr, line });
                                 initVar = { kind: "var", name: tempName };
@@ -1859,6 +1860,9 @@ function extractFunctionInner(fn, parentAnnotations) {
 }
 // ── Module extraction ────────────────────────────────────────
 export function extractModule(sourceFile) {
+    // Seed the fresh-name check (names.ts) before anything mints: every
+    // Identifier token in the module, a deliberate over-approximation.
+    setUserNames(new Set(sourceFile.getDescendantsOfKind(SyntaxKind.Identifier).map(i => i.getText())));
     const typeDecls = [];
     // Cross-file calls are auto-externed: ts-morph resolves the call's symbol;
     // if it's defined in a different source file we treat the symbol as opaque

package/tools/dist/ir.js

@@ -60,3 +60,23 @@ export function anyExprInStmt(s, pred) {
 export function anyExprInStmts(stmts, pred) {
     return stmts.some(s => anyExprInStmt(s, pred));
 }
+// A name is "used" — such that a synthesized binder of the same name would
+// capture or shadow it — iff it appears as a variable reference or a called
+// function. These drive the *local* freshness checks for user-facing binders
+// (the result out-parameter, comprehension binders): a binder is checked only
+// against the expressions/scope it actually wraps, not the whole module.
+const _refsName = (name) => e => (e.kind === "var" && e.name === name) ||
+    (e.kind === "app" && e.fn === name) ||
+    (e.kind === "constructor" && e.name === name) ||
+    (e.kind === "match" && typeof e.scrutinee === "string" && e.scrutinee === name);
+export function usesName(e, name) {
+    return anyExpr(e, _refsName(name));
+}
+export function usesNameInStmts(stmts, name) {
+    return anyExprInStmts(stmts, _refsName(name));
+}
+/** Does a declaration's spec (requires/ensures) or body reference `name`? The
+ *  scope a method's out-parameter binder must dodge, shared by both emitters. */
+export function usesNameInDecl(requires, ensures, body, name) {
+    return requires.some(e => usesName(e, name)) || ensures.some(e => usesName(e, name)) || usesNameInStmts(body, name);
+}

package/tools/dist/lean-emit.js

@@ -2,7 +2,8 @@
  * Lean emitter — IR → Lean text.
  * No logic, no type decisions — just serialization.
  */
-import { anyExpr } from "./ir.js";
+import { anyExpr, usesNameInDecl } from "./ir.js";
+import { freshName } from "./names.js";
 // ── Ty → Lean type string ──────────────────────────────────
 function tyToLean(ty) {
     switch (ty.kind) {
@@ -76,11 +77,15 @@ const LEAN_KEYWORDS = new Set([
     "partial", "unsafe", "macro", "syntax", "by", "fun", "have", "show",
     "at", "from", "to", "deriving", "extends", "true", "false",
 ]);
+// The return-value identifier for the method currently being emitted. Default
+// `res`, but primed (e.g. `res'`) when a module identifier is named `res` — set
+// by the method case. `\result` in an ensures/body must use the same name.
+let _resultName = "res";
 function escapeName(name) {
     // \result is carried through the IR as the var name "\\result"; render it
-    // as Lean's canonical return-value identifier (matches `return (res : T)`).
+    // as the method's return-value identifier (matches `return (res : T)`).
     if (name === "\\result")
-        return "res";
+        return _resultName;
     return LEAN_KEYWORDS.has(name) ? `«${name}»` : name;
 }
 // ── Operator precedence (for parenthesization) ──────────────
@@ -258,6 +263,8 @@ function emitMethodCall(tyKind, method, monadic, obj, args) {
             return `${obj}.contains ${args[0]}`;
         if (method === "set")
             return `${obj}.insert ${args[0]} ${args[1]}`;
+        if (method === "delete")
+            return `${obj}.erase ${args[0]}`;
     }
     // Set methods
     if (tyKind === "set") {
@@ -680,7 +687,12 @@ function emitDecl(d) {
             // Spec clauses are Prop; the `do` body is computational (Bool).
             const prevBoolCtx = _boolCtx;
             _boolCtx = false;
-            const lines = [`method ${d.name} ${params} return (res : ${tyToLean(d.returnType)})`];
+            // Prime the return binder only on a collision within *this method's own*
+            // signature/body — `res` is a common identifier module-wide (record
+            // fields, unrelated params), so a module-wide check would prime spuriously.
+            _resultName = freshName("res", n => d.params.some(p => escapeName(p.name) === n) ||
+                usesNameInDecl(d.requires, d.ensures, d.body, n));
+            const lines = [`method ${d.name} ${params} return (${_resultName} : ${tyToLean(d.returnType)})`];
             for (const r of d.requires)
                 lines.push(`  require ${emitExpr(r)}`);
             for (const e of d.ensures)

package/tools/dist/lsc.js

@@ -5,7 +5,9 @@
  * Pipeline: extract → resolve → narrow → transform → peephole → emit
  */
 import { Project, ScriptTarget } from "ts-morph";
-import { existsSync } from "fs";
+import { existsSync, readFileSync } from "fs";
+import { execFileSync } from "child_process";
+import { createRequire } from "module";
 import path from "path";
 import { extractModule } from "./extract.js";
 import { resolveModule } from "./resolve.js";
@@ -20,20 +22,44 @@ import { leanGen, leanCheck } from "./lean-commands.js";
 import { runInfo } from "./info-command.js";
 function main() {
     const args = process.argv.slice(2);
-    // `lsc claimcheck …` forwards verbatim to the lemmascript-claimcheck CLI
-    // (a dependency; its cli reads the rewritten process.argv).
+    // `lsc claimcheck <file.ts> …` forwards verbatim to the lemmascript-claimcheck
+    // CLI (a dependency; its cli reads the rewritten process.argv). With no
+    // leading <file.ts>, batch: one satellite run per LemmaScript-files.txt entry,
+    // flags passed through unchanged — the loop is owned here, the satellite
+    // stays single-file.
     if (args[0] === "claimcheck") {
-        process.argv = [process.argv[0], "lemmascript-claimcheck", ...args.slice(1)];
-        import("lemmascript-claimcheck/cli").catch((err) => {
-            const code = err?.code;
-            if (code === "ERR_MODULE_NOT_FOUND" || code === "ERR_PACKAGE_PATH_NOT_EXPORTED") {
-                console.error("`lsc claimcheck` needs lemmascript-claimcheck >= 0.2.0; reinstall with: npm i -g lemmascript");
-            }
-            else {
+        const rest = args.slice(1);
+        const missing = () => {
+            console.error("`lsc claimcheck` needs lemmascript-claimcheck >= 0.2.0; reinstall with: npm i -g lemmascript");
+            process.exit(1);
+        };
+        if (rest[0] && !rest[0].startsWith("-")) {
+            process.argv = [process.argv[0], "lemmascript-claimcheck", ...rest];
+            import("lemmascript-claimcheck/cli").catch((err) => {
+                const code = err?.code;
+                if (code === "ERR_MODULE_NOT_FOUND" || code === "ERR_PACKAGE_PATH_NOT_EXPORTED")
+                    missing();
                 console.error(err instanceof Error ? err.message : String(err));
+                process.exit(1);
+            });
+            return;
+        }
+        let cli;
+        try {
+            cli = createRequire(import.meta.url).resolve("lemmascript-claimcheck/cli");
+        }
+        catch {
+            missing();
+            return;
+        }
+        for (const e of readEntries()) {
+            try {
+                execFileSync(process.execPath, [cli, e.file, ...rest], { stdio: "inherit" });
             }
-            process.exit(1);
-        });
+            catch {
+                process.exit(1);
+            }
+        }
         return;
     }
     const backendIdx = args.findIndex(a => a.startsWith("--backend="));
@@ -50,7 +76,12 @@ function main() {
     const timeLimitIdx = args.findIndex(a => a.startsWith("--time-limit="));
     let timeLimit;
     if (timeLimitIdx >= 0) {
-        timeLimit = parseInt(args[timeLimitIdx].split("=")[1]);
+        const val = args[timeLimitIdx].split("=")[1];
+        if (!/^[1-9]\d*$/.test(val)) {
+            console.error(`Invalid --time-limit: ${val} (expected seconds as a positive integer)`);
+            process.exit(1);
+        }
+        timeLimit = parseInt(val);
         args.splice(timeLimitIdx, 1);
     }
     const extraFlagsIdx = args.findIndex(a => a.startsWith("--extra-flags="));
@@ -59,12 +90,71 @@ function main() {
         extraFlags = args[extraFlagsIdx].split("=").slice(1).join("=");
         args.splice(extraFlagsIdx, 1);
     }
+    // --slow (batch mode only): verify every entry with its own timeout instead
+    // of degrading slow ones to gen-check.
+    let slow = false;
+    const slowIdx = args.indexOf("--slow");
+    if (slowIdx >= 0) {
+        slow = true;
+        args.splice(slowIdx, 1);
+    }
+    // Anything flag-shaped left over is a typo or a space-separated form
+    // (`--backend lean`): reject it rather than let it become a positional arg
+    // or be silently ignored (which would e.g. verify with the wrong backend).
+    const stray = args.find(a => a.startsWith("-"));
+    if (stray) {
+        console.error(`Unknown flag: ${stray} (flags take the form --flag=value, e.g. --backend=dafny)`);
+        process.exit(1);
+    }
     const [cmd, filePath] = args;
-    if (!cmd || !filePath) {
+    if (!cmd) {
         console.error("Usage: lsc <gen|check|regen|extract|info> [--backend=lean|dafny] <file.ts>");
-        console.error("       lsc claimcheck <file.ts> [flags…]   (forwards to lemmascript-claimcheck)");
+        console.error("       lsc <gen|gen-check|check> [--backend=…] [--slow]   (no file: batch over LemmaScript-files.txt)");
+        console.error("       lsc claimcheck [<file.ts>] [flags…]   (forwards to lemmascript-claimcheck)");
+        process.exit(1);
+    }
+    if (!filePath) {
+        runBatch(cmd, backend, slow);
+        return;
+    }
+    runFile(cmd, filePath, backend, timeLimit, extraFlags);
+}
+// LemmaScript-files.txt, parsed: `filepath [timeout_in_seconds] [extra dafny
+// flags…]` per line; no timeout = Dafny default. Exits if the file is absent.
+function readEntries() {
+    if (!existsSync("LemmaScript-files.txt")) {
+        console.error("No file given and no LemmaScript-files.txt found.");
         process.exit(1);
     }
+    return readFileSync("LemmaScript-files.txt", "utf8")
+        .split("\n").map(s => s.trim()).filter(Boolean)
+        .map(entry => {
+        const [file, second, ...rest] = entry.split(/\s+/);
+        const timeout = second && /^[1-9]\d*$/.test(second) ? parseInt(second) : undefined;
+        const flags = (timeout === undefined ? [second, ...rest] : rest).filter(Boolean).join(" ") || undefined;
+        return { file, timeout, flags };
+    });
+}
+// Batch over LemmaScript-files.txt. `check` entries with a timeout above 60s
+// (the CI limit) are gen-check only, unless --slow. Fail-fast: the first
+// failing entry exits. tools/check.sh drives this from source;
+// installed-package consumers run `lsc check`.
+function runBatch(cmd, backend, slow) {
+    if (cmd !== "gen" && cmd !== "gen-check" && cmd !== "check") {
+        console.error(`No file given, and batch mode supports gen|gen-check|check (not ${cmd}).`);
+        process.exit(1);
+    }
+    for (const e of readEntries()) {
+        if (cmd === "check" && backend === "dafny" && !slow && e.timeout !== undefined && e.timeout > 60) {
+            console.log(`=== ${path.basename(e.file)} (timeout ${e.timeout}s > 60s, gen-check only) ===`);
+            runFile("gen-check", e.file, backend, undefined, undefined);
+        }
+        else {
+            runFile(cmd, e.file, backend, e.timeout, e.flags);
+        }
+    }
+}
+function runFile(cmd, filePath, backend, timeLimit, extraFlags) {
     const absPath = path.resolve(filePath);
     if (!existsSync(absPath)) {
         console.error(`File not found: ${absPath}`);
@@ -157,7 +247,7 @@ function main() {
             return;
         }
         if (cmd === "regen") {
-            dafnyRegen(genPath, dfyPath, basePath, text, dir);
+            dafnyRegen(genPath, dfyPath, basePath, text, dir, timeLimit, extraFlags);
             return;
         }
         console.error(`Unknown command: ${cmd}`);

package/tools/dist/names.js

@@ -0,0 +1,47 @@
+/**
+ * Fresh names for toolchain-minted identifiers.
+ *
+ * Several passes synthesize names — loop counters (`_x_idx`), lift temps
+ * (`_t0`), someMatch binders (`_task_val`), quantifier binders. Any such name
+ * can collide with a user-written identifier and either capture it (silently
+ * changing semantics — the `.delete()` binder bug) or shadow it (a
+ * loud duplicate-variable error in the backend).
+ *
+ * The rule, chosen for zero churn to existing output: a minted name is used
+ * verbatim unless the user wrote the same identifier somewhere in the module,
+ * in which case a prime (`'`) is appended. TypeScript identifiers cannot
+ * contain a prime, while Dafny and Lean both accept them, so one prime always
+ * suffices; and priming preserves distinctness among minted names, so the
+ * existing counter/suffix schemes keep working unchanged.
+ *
+ * The module-wide check deliberately over-approximates scope — a colliding
+ * name anywhere in the file primes the mint. False positives only affect
+ * internal names nobody reads. Names with a user-facing meaning stay exact by
+ * different, local means: comprehension binders check the expressions they
+ * actually wrap (`usesName` in dafny-emit), and result binders check the
+ * signature/body in hand (`methodHeader`). Spec text (`//@` comments) is NOT
+ * scanned: specs may legitimately reference minted names (e.g. `_x_idx` loop
+ * counters in invariants), so a spec mention is a reference, not a collision
+ * — when a source collision does force a prime, spec references are expected
+ * to follow it.
+ */
+let _userNames = new Set();
+/** Seeded once per module by extract with every Identifier token in the
+ *  source — params, locals, fields, callees alike. */
+export function setUserNames(names) {
+    _userNames = names;
+}
+export function isUserName(name) {
+    return _userNames.has(name);
+}
+/** A toolchain-internal name: `base` verbatim, primed on collision. The one
+ *  place the priming rule lives. `taken` says what counts as a collision —
+ *  by default a user-written name anywhere in the module; callers that know
+ *  the exact scope (e.g. a comprehension binder checking only the expressions
+ *  it wraps) pass their own predicate. */
+export function freshName(base, taken = isUserName) {
+    let name = base;
+    while (taken(name))
+        name += "'";
+    return name;
+}

package/tools/dist/narrow.js

@@ -34,6 +34,7 @@
  * (early-return, let-cond) run in `walkStmts` so they can consume the rest
  * of the block.
  */
+import { freshName } from "./names.js";
 // ── Optional-check detection ────────────────────────────────
 /** Counter for naming optChain binders. Reset per module. */
 let _ocCounter = 0;
@@ -52,7 +53,7 @@ function parseOptionalCheck(cond) {
         const hint = binderHintFor(e);
         if (hint === null)
             return null;
-        return { scrutinee: e, innerTy, negated: true, binderHint: hint, truthiness: true };
+        return { scrutinee: e, innerTy, negated: true, binderHint: freshName(hint), truthiness: true };
     }
     if (cond.kind !== "binop" || (cond.op !== "!==" && cond.op !== "===")) {
         // Bare optional truthiness: `if (e)` where e: T | undefined — true iff e is
@@ -61,7 +62,7 @@ function parseOptionalCheck(cond) {
             const hint = binderHintFor(cond);
             if (hint === null)
                 return null;
-            return { scrutinee: cond, innerTy: cond.ty.inner, negated: false, binderHint: hint, truthiness: true };
+            return { scrutinee: cond, innerTy: cond.ty.inner, negated: false, binderHint: freshName(hint), truthiness: true };
         }
         return null;
     }
@@ -77,7 +78,7 @@ function parseOptionalCheck(cond) {
     const hint = binderHintFor(e);
     if (hint === null)
         return null;
-    return { scrutinee: e, innerTy: e.ty.inner, negated: cond.op === "===", binderHint: hint, truthiness: false };
+    return { scrutinee: e, innerTy: e.ty.inner, negated: cond.op === "===", binderHint: freshName(hint), truthiness: false };
 }
 function binderHintFor(e) {
     // Pure access paths: var(x) or field(purePath, name).
@@ -425,7 +426,7 @@ function ruleNullish(e) {
     if (e.left.ty.kind !== "optional")
         return null;
     const innerTy = e.left.ty.inner;
-    const binder = `_oc${_ocCounter++}_val`;
+    const binder = freshName(`_oc${_ocCounter++}_val`);
     return {
         kind: "someMatch",
         scrutinee: e.left, binder, binderTy: innerTy,
@@ -499,7 +500,7 @@ function ruleOptChain(e) {
     if (e.obj.ty.kind !== "optional")
         return null;
     const innerTy = e.obj.ty.inner;
-    const binder = `_oc${_ocCounter++}_val`;
+    const binder = freshName(`_oc${_ocCounter++}_val`);
     let body = { kind: "var", name: binder, ty: innerTy };
     for (const step of e.chain) {
         if (step.kind === "field") {
@@ -543,9 +544,9 @@ function binderHintForMapAccess(m, k) {
         // mHint is `_m_val`, kHint is `_k_val` — stitch into `_m_k_val`.
         const mStem = mHint.replace(/_val$/, "");
         const kStem = kHint.replace(/^_/, "").replace(/_val$/, "");
-        return `${mStem}_${kStem}_val`;
+        return freshName(`${mStem}_${kStem}_val`);
     }
-    return `_oc${_ocCounter++}_val`;
+    return freshName(`_oc${_ocCounter++}_val`);
 }
 /** Rule (expression): `k in m ? m[k] : default` where m is map-typed.
  *  The then-branch must be exactly `m[k]` (same obj, same key). This mirrors
@@ -592,9 +593,10 @@ function ruleConditionalOptionalTruthy(e) {
         return null;
     if (e.cond.ty.kind !== "optional")
         return null;
-    const binder = binderHintFor(e.cond);
-    if (binder === null)
+    const hint = binderHintFor(e.cond);
+    if (hint === null)
         return null;
+    const binder = freshName(hint);
     return {
         kind: "someMatch",
         scrutinee: e.cond, binderTy: e.cond.ty.inner,

package/tools/dist/resolve.js

@@ -7,6 +7,7 @@
 import { isBigInt } from "./typedir.js";
 import { parseTsType, tyToCanonical } from "./types.js";
 import { parseExpr } from "./specparser.js";
+import { freshName } from "./names.js";
 function lookup(env, name) {
     if (!env)
         return undefined;
@@ -693,7 +694,7 @@ function resolveRecordMerge(base, override, ctx) {
                 return { name: f.name, value: ovf }; // required: override always provides
             // optional: override field wins iff present, else base's field
             const bvf = { kind: "field", obj: bv, field: f.name, ty: ft };
-            const binder = `_m${mergeBinder++}`;
+            const binder = freshName(`_m${mergeBinder++}`);
             // someBody is the unwrapped present value; transform re-wraps each arm in
             // the backend's Some constructor (Dafny `Some`, Lean `Option.some`).
             return { name: f.name, value: {
@@ -704,7 +705,7 @@ function resolveRecordMerge(base, override, ctx) {
     });
     if (tover.ty.kind === "optional") {
         // override may be absent (undefined spreads nothing) → base unchanged
-        const binder = `_mo${mergeBinder++}`;
+        const binder = freshName(`_mo${mergeBinder++}`);
         return {
             kind: "someMatch", scrutinee: tover, binder, binderTy: userTy,
             someBody: merged(tbase, { kind: "var", name: binder, ty: userTy }), noneBody: tbase, ty: userTy,
@@ -1373,7 +1374,9 @@ function resolveStmt(s, ctx) {
                 for (const _ of s.names)
                     nameTypes.push({ kind: "unknown" });
             }
-            const idxName = `_${s.names[0]}_idx`;
+            // Must match the freshened counter transform mints for this loop, so a
+            // spec referencing the loop index resolves to the same name.
+            const idxName = freshName(`_${s.names[0]}_idx`);
             env = extend(env, idxName, { kind: "nat" });
             for (let j = 0; j < s.names.length; j++) {
                 env = extend(env, s.names[j], nameTypes[j] ?? { kind: "unknown" });

package/tools/dist/transform.js

@@ -6,6 +6,7 @@
  */
 import { anyExprInStmts } from "./ir.js";
 import { parseTsType } from "./types.js";
+import { freshName } from "./names.js";
 // ── Generic IR walkers ──────────────────────────────────────
 /**
  * Map over all sub-expressions in an Expr. `f` is called on each node;
@@ -73,6 +74,54 @@ function mapStmt(s, f) {
         case "assert": return { ...s, expr: r(s.expr) };
     }
 }
+/** Binders a match-arm pattern string (`.Ctor a b`, `_x_val`, `_`) introduces. */
+function patternBinders(pattern) {
+    const toks = pattern.match(/[A-Za-z_][A-Za-z0-9_']*/g) ?? [];
+    return pattern.trimStart().startsWith(".") ? toks.slice(1) : toks;
+}
+/** Rename free occurrences of `from` to `to`, stopping at every construct that
+ *  rebinds `from` — lambda params, `let`/`let-bind`/`ghostLet` (shadows the
+ *  rest of the block), `match` arm patterns, `forall`/`exists`, and `for-in`
+ *  indices. Capture-avoiding: a nested scope that reintroduces `from` keeps its
+ *  own binding untouched. `mapExpr` doesn't descend into lambda bodies, so this
+ *  walks them by hand. */
+export function renameFreeVar(e, from, to) {
+    const f = (x) => {
+        if (x.kind === "var")
+            return x.name === from ? { ...x, name: to } : x;
+        // let-expression: `value` is in the outer scope (rename), `body` sees the
+        // rebound `from` (leave it), so handle the recursion here to stop descent.
+        if (x.kind === "let" && x.name === from)
+            return { ...x, value: mapExpr(x.value, f) };
+        if ((x.kind === "forall" || x.kind === "exists") && x.var === from)
+            return x;
+        if (x.kind === "match") {
+            const scr = typeof x.scrutinee === "string"
+                ? (x.scrutinee === from ? to : x.scrutinee) : mapExpr(x.scrutinee, f);
+            return { ...x, scrutinee: scr, arms: x.arms.map(a => patternBinders(a.pattern).includes(from) ? a : { ...a, body: mapExpr(a.body, f) }) };
+        }
+        if (x.kind === "lambda") {
+            if (x.params.some(p => p.name === from))
+                return x; // param shadows `from`
+            const body = [];
+            let shadowed = false;
+            for (const s of x.body) {
+                if (shadowed) {
+                    body.push(s);
+                    continue;
+                }
+                body.push(s.kind === "forin" && s.idx === from
+                    ? { ...s, bound: mapExpr(s.bound, f) } // idx shadows in the loop body
+                    : mapStmt(s, f));
+                if ((s.kind === "let" || s.kind === "let-bind" || s.kind === "ghostLet") && s.name === from)
+                    shadowed = true;
+            }
+            return { ...x, body };
+        }
+        return null;
+    };
+    return mapExpr(e, f);
+}
 /** Map over all sub-expressions in a TExpr (typed IR). */
 function mapTExpr(e, f) {
     const hit = f(e);
@@ -145,9 +194,12 @@ let _opts = DAFNY_OPTIONS;
 let _typeDecls = [];
 /** Prefix match-bound field names to avoid capturing user variables.
  *  When prefix is given (the scrutinee name), include it to avoid
- *  collisions in nested matches on different variables. */
+ *  collisions in nested matches on different variables. `freshName` closes
+ *  the residual gap: a user variable literally named `_value`/`_x_field` in an
+ *  arm body would still be captured, so prime on any module-wide collision.
+ *  Deterministic, so the pattern binder and its body substitutions agree. */
 function matchBinder(fieldName, prefix) {
-    return prefix ? `_${prefix}_${fieldName}` : `_${fieldName}`;
+    return freshName(prefix ? `_${prefix}_${fieldName}` : `_${fieldName}`);
 }
 /** Build a match arm pattern like `.VariantName _v_field1 _v_field2` from variant info. */
 function buildMatchPattern(variantName, fields, scopePrefix) {
@@ -351,7 +403,7 @@ function lowerExpr(e, binds) {
     // callKind "unknown" and fall through to the regular case below where
     // they become `methodCall`.
     if (binds && e.kind === "call" && e.callKind === "method" && e.fn.kind === "var") {
-        const name = `_t${_liftCounter++}`;
+        const name = freshName(`_t${_liftCounter++}`);
         const args = e.args.map(a => lowerExpr(a, binds));
         binds.push({ kind: "let-bind", name, value: { kind: "app", fn: e.fn.name, args } });
         return { kind: "var", name };
@@ -751,7 +803,7 @@ function lowerExpr(e, binds) {
                 const result = { kind: "methodCall", obj: recv, objTy: e.fn.obj.ty, method, args, monadic: needsMonadic };
                 // Monadic HOF call is itself monadic — lift via binds like a method call
                 if (_opts.monadic && needsMonadic && binds) {
-                    const name = `_t${_liftCounter++}`;
+                    const name = freshName(`_t${_liftCounter++}`);
                     binds.push({ kind: "let-bind", name, value: result });
                     return { kind: "var", name };
                 }
@@ -911,7 +963,7 @@ function lowerExpr(e, binds) {
         case "havoc":
             // Dafny's * only works in var/assign positions — lift to own declaration
             if (binds) {
-                const name = `_t${_liftCounter++}`;
+                const name = freshName(`_t${_liftCounter++}`);
                 binds.push({ kind: "let", name, type: e.ty, mutable: false, value: { kind: "havoc", type: e.ty } });
                 return { kind: "var", name };
             }
@@ -1357,11 +1409,11 @@ function transformStmts(stmts, typeDecls) {
                 const count = _forofCounters.get(keyName) ?? 0;
                 _forofCounters.set(keyName, count + 1);
                 const suffix = count === 0 ? "" : `${count + 1}`;
-                const keysSeqName = `_${keyName}_keys${suffix}`;
+                const keysSeqName = freshName(`_${keyName}_keys${suffix}`);
                 const convExpr = { kind: "app", fn: "SetToSeq", args: [{ kind: "field", obj: iterExpr, field: "keys" }] };
                 result.push({ kind: "let", name: keysSeqName, type: { kind: "array", elem: keyTy }, mutable: false, value: convExpr });
                 const keysVar = { kind: "var", name: keysSeqName };
-                const idxName = `_${keyName}_idx${suffix}`;
+                const idxName = freshName(`_${keyName}_idx${suffix}`);
                 const idx = { kind: "var", name: idxName };
                 const arrSize = { kind: "field", obj: keysVar, field: "size" };
                 const bodyStmts = eliminateTopLevelContinue(transformStmts(s.body, typeDecls));
@@ -1383,11 +1435,11 @@ function transformStmts(stmts, typeDecls) {
                 const count = _forofCounters.get(keyName) ?? 0;
                 _forofCounters.set(keyName, count + 1);
                 const suffix = count === 0 ? "" : `${count + 1}`;
-                const keysSeqName = `_${keyName}_keys${suffix}`;
+                const keysSeqName = freshName(`_${keyName}_keys${suffix}`);
                 const convExpr = { kind: "app", fn: "SetToSeq", args: [{ kind: "field", obj: iterExpr, field: "keys" }] };
                 result.push({ kind: "let", name: keysSeqName, type: { kind: "array", elem: keyTy }, mutable: false, value: convExpr });
                 const keysVar = { kind: "var", name: keysSeqName };
-                const idxName = `_${keyName}_idx${suffix}`;
+                const idxName = freshName(`_${keyName}_idx${suffix}`);
                 const idx = { kind: "var", name: idxName };
                 const arrSize = { kind: "field", obj: keysVar, field: "size" };
                 const bodyStmts = eliminateTopLevelContinue(transformStmts(s.body, typeDecls));
@@ -1405,7 +1457,7 @@ function transformStmts(stmts, typeDecls) {
             }
             // Sets aren't indexable — bind SetToSeq to a variable for iteration
             if (s.iterable.ty.kind === "set") {
-                const seqName = `_${varName}_seq`;
+                const seqName = freshName(`_${varName}_seq`);
                 const convExpr = { kind: "app", fn: "SetToSeq", args: [iterExpr] };
                 const elemTy = varTy.kind !== "unknown" ? varTy : { kind: "string" };
                 result.push({ kind: "let", name: seqName, type: { kind: "array", elem: elemTy }, mutable: false, value: convExpr });
@@ -1414,7 +1466,7 @@ function transformStmts(stmts, typeDecls) {
             const count = _forofCounters.get(varName) ?? 0;
             _forofCounters.set(varName, count + 1);
             const suffix = count === 0 ? "" : `${count + 1}`;
-            const idxName = `_${varName}_idx${suffix}`;
+            const idxName = freshName(`_${varName}_idx${suffix}`);
             const idx = { kind: "var", name: idxName };
             const arrSize = { kind: "field", obj: iterExpr, field: "size" };
             const bodyStmts = eliminateTopLevelContinue(transformStmts(s.body, typeDecls));
@@ -1489,15 +1541,17 @@ function transformStmt(s, typeDecls) {
                     const arrIR = transformExpr(arrExpr);
                     const arrTy = arrExpr.ty;
                     const elemTy = arrTy.kind === "array" ? arrTy.elem : { kind: "unknown" };
-                    const idxName = `_${param}_idx`;
+                    const idxName = freshName(`_${param}_idx`);
                     const idx = { kind: "var", name: idxName };
                     const arrSize = { kind: "field", obj: arrIR, field: "size" };
                     const elemVar = { kind: "var", name: param };
                     const keyIR = transformExpr(keyExpr);
                     const valIR = transformExpr(valExpr);
                     const mapSet = { kind: "methodCall", obj: { kind: "var", name: s.name }, objTy: s.ty, method: "set", args: [keyIR, valIR], monadic: false };
-                    // Auto-invariant: all processed elements' keys are in the map
-                    const kVar = { kind: "var", name: "ki" };
+                    // Auto-invariant: all processed elements' keys are in the map. The
+                    // quantifier wraps user expressions, so its binder must be fresh.
+                    const kiName = freshName("ki");
+                    const kVar = { kind: "var", name: kiName };
                     const mapHasKey = {
                         kind: "implies",
                         premises: [
@@ -1506,7 +1560,7 @@ function transformStmt(s, typeDecls) {
                         ],
                         conclusion: { kind: "methodCall", obj: { kind: "var", name: s.name }, objTy: s.ty, method: "has", args: [keyIR.kind === "field" ? { kind: "field", obj: { kind: "index", arr: arrIR, idx: kVar }, field: keyIR.field } : keyIR], monadic: false },
                     };
-                    const autoInv = { kind: "forall", var: "ki", type: { kind: "int" }, body: mapHasKey };
+                    const autoInv = { kind: "forall", var: kiName, type: { kind: "int" }, body: mapHasKey };
                     const stmts = [
                         { kind: "let", name: s.name, type: s.ty, mutable: true, value: { kind: "emptyMap" } },
                         { kind: "forin", idx: idxName, bound: arrSize,