lemmascript 0.6.0 → 0.6.1

package/README.md

@@ -14,7 +14,7 @@ Each example and case study is verified in Lean 4 and/or Dafny from the same ann
 
 See the internal [examples](examples).
 
-See the external case studies:
+See the external [case studies](https://github.com/search?q=topic%3Alemmascript+topic%3Acase-study&type=repositories):
 - **[collab-todo-lemmascript](https://github.com/midspiral/collab-todo-lemmascript/)** — collaborative task management web app (React + Supabase) with a verified domain model. Single `domain.ts` imported directly by the UI, hooks, and edge functions — no adapter layer. 123 Dafny lemmas (120 in a separate `domain.proofs.dfy`): 16-conjunct invariant preserved across 25 single-project + 3 cross-project actions, NoOp completeness/soundness, initialization. Dafny only.
 - **[colorwheel-lemmascript](https://github.com/midspiral/colorwheel-lemmascript/)** — verified color palette generator with mood + harmony constraints. 31 Lean proofs + 18 behavioral properties, 115 Dafny lemmas (invariant preservation, commutativity, NoOp completeness).
 - **[clear-split-lemmascript](https://github.com/midspiral/clear-split-lemmascript/)** — greenfield verified expense splitting web app. Conservation theorem, invariant preservation, delta laws — all proven in both Lean (no sorry) and Dafny (56 lemmas).

package/package.json

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

package/tools/dist/dafny-emit.js

@@ -189,12 +189,12 @@ function escapeGeneratedName(name) {
 function paramList(params) {
     return params.map(p => `${escapeName(p.name)}: ${tyToDafny(p.type)}`).join(", ");
 }
-/** 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, scope) {
+/** Format a method signature header, normally omitting `returns` for void
+ *  methods. A body-less impure extern opts into a Unit out-parameter so the
+ *  shared method-call lifting can bind its call like any other expression. */
+function methodHeader(prefix, params, returnType, scope, includeVoidReturn = false) {
     const sig = `${prefix}(${paramList(params)})`;
-    if (returnType.kind === "void")
+    if (returnType.kind === "void" && !includeVoidReturn)
         return sig;
     // 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
@@ -993,10 +993,20 @@ function emitDecl(d) {
             return `const ${escapeName(d.name)}: ${tyToDafny(d.type)} := ${emitExpr(d.value)}`;
         }
         case "extern": {
-            // Body-less Dafny function — `:axiom` makes Dafny accept the missing body
-            // and treats it as an uninterpreted symbol. Any `requires`/`ensures` were
-            // lifted from the source declaration's annotations.
+            // `:axiom` makes Dafny accept the missing body. Pure externs are
+            // uninterpreted functions (deterministic/extensional); impure externs are
+            // methods, so every invocation gets an independent arbitrary result
+            // constrained only by its per-call contract.
             const tp = d.typeParams.length > 0 ? `<${d.typeParams.join(", ")}>` : "";
+            if (d.impure) {
+                const scope = { requires: d.requires, ensures: d.ensures, body: [] };
+                const lines = [methodHeader(`method {:axiom} ${escapeName(d.name)}${tp}`, d.params, d.returnType, scope, true)];
+                for (const r of d.requires)
+                    lines.push(`  requires ${emitExpr(r)}`);
+                for (const e of d.ensures)
+                    lines.push(`  ensures ${emitExpr(e)}`);
+                return lines.join("\n");
+            }
             const lines = [`function {:axiom} ${escapeName(d.name)}${tp}(${paramList(d.params)}): ${tyToDafny(d.returnType)}`];
             for (const r of d.requires)
                 lines.push(`  requires ${emitExpr(r)}`);

package/tools/dist/extract.js

@@ -32,7 +32,8 @@ function withHavocKey(key, fn) {
 }
 /** Auto-detected cross-file calls. Populated by `extractExpr` whenever it sees
  *  a call `Obj.method(...)` or `foo(...)` whose ts-morph symbol resolves to a
- *  different `.ts` source file. Emitted in Dafny as `function {:axiom} <flat>`.
+ *  different `.ts` source file. Emitted in Dafny as `function {:axiom} <flat>`
+ *  by default, or as a body-less method when the source has `//@ impure`.
  *  Cleared at the start of every `extractModule`. */
 const _externs = new Map();
 /** Signature types of *kept* externs, for the imported-type resolver: a type
@@ -163,7 +164,8 @@ function detectCrossFileExtern(callee, sourceFile, sigTypesOut) {
     const annots = collectFunctionAnnotations(externalDecl);
     const requires = annots.filter(a => a.kind === "requires").map(a => a.expr);
     const ensures = annots.filter(a => a.kind === "ensures").map(a => a.expr);
-    return { qualified, flat, typeParams, params, returnType, requires, ensures };
+    const impure = hasBareFunctionAnnotation(externalDecl, "impure");
+    return { qualified, flat, typeParams, params, returnType, requires, ensures, impure };
 }
 /** Build a concat-tree from a mixed list of literal and SpreadElement nodes.
  *  Literals collapse into arrayLiteral segments; spreads become bare expressions;
@@ -761,17 +763,27 @@ function collectFunctionAnnotations(fn) {
     }
     return collectAnnotations(fn);
 }
-/** Check for bare `//@ pure` annotation (no expression). */
-function hasPureAnnotation(node, body) {
+/** Check for a bare function annotation such as `//@ pure` or `//@ impure`.
+ *  Function annotations may precede the declaration or its first statement. */
+function hasBareFunctionAnnotation(node, keyword, body) {
+    if (!body) {
+        const fnBody = node.getBody?.();
+        if (fnBody && Node.isBlock(fnBody))
+            body = fnBody.getStatements();
+    }
     const nodes = body && body.length > 0 ? [node, body[0]] : [node];
     for (const n of nodes) {
         for (const range of n.getLeadingCommentRanges()) {
-            if (range.getText().trim() === "//@ pure")
+            if (range.getText().trim() === `//@ ${keyword}`)
                 return true;
         }
     }
     return false;
 }
+/** Check for bare `//@ pure` annotation (no expression). */
+function hasPureAnnotation(node, body) {
+    return hasBareFunctionAnnotation(node, "pure", body);
+}
 // ── Type declaration extraction ──────────────────────────────
 function extractTypeDecl(decl, extraDecls) {
     const name = decl.getName();
@@ -2235,6 +2247,12 @@ export function extractModule(sourceFile) {
         }
         return false;
     }
+    function hasImpure(f) {
+        if (hasBareFunctionAnnotation(f.node, "impure"))
+            return true;
+        return !!f.parentStmt && f.parentStmt.getLeadingCommentRanges()
+            .some(r => r.getText().trim() === "//@ impure");
+    }
     // `//@ extern NS.method` registers the extern under a *dotted* qualified name,
     // so a real `NS.method(args)` call dispatches to it (resolve.ts) with no
     // wrapper — e.g. `//@ extern fs.readFileSync` lets you call `fs.readFileSync`
@@ -2277,7 +2295,10 @@ export function extractModule(sourceFile) {
         const annots = collectFunctionAnnotations(f.node);
         const requires = annots.filter(a => a.kind === "requires").map(a => a.expr);
         const ensures = annots.filter(a => a.kind === "ensures").map(a => a.expr);
-        _externs.set(qualified, { qualified, flat, typeParams, params, returnType, requires, ensures });
+        _externs.set(qualified, {
+            qualified, flat, typeParams, params, returnType, requires, ensures,
+            impure: hasImpure(f),
+        });
     }
     // If any function has //@ verify, only extract those (brownfield mode).
     // For expression-body arrows, //@ verify may be on the parent variable statement.

package/tools/dist/lean-emit.js

@@ -838,6 +838,9 @@ function emitDecl(d) {
         case "const":
             return `def ${escapeName(d.name)} : ${tyToLean(d.type)} := ${emitExpr(d.value)}`;
         case "extern": {
+            if (d.impure) {
+                throw new Error("//@ impure extern is not supported in the Lean backend");
+            }
             // Mirror Dafny's `function {:axiom}`: an uninterpreted total function.
             // In Lean that is an `opaque` declaration (sound — it commits to no body,
             // only to the type being inhabited). Any `requires`/`ensures` the source

package/tools/dist/resolve.js

@@ -453,12 +453,21 @@ function classifyCall(fn, ctx) {
         return "pure";
     if (fn.kind === "var" && (ctx.inSpec || ctx.inLambda) && ctx.pureFns.has(fn.name))
         return "spec-pure";
-    // Bare-name `//@ extern` declarations are emitted as `function {:axiom}` —
-    // pure from the verifier's perspective. Classify them as pure so callers
-    // don't get lifted to statement-level binds (which would force lambdas to
-    // become multi-statement, illegal in Dafny).
-    if (fn.kind === "var" && ctx.externs.has(fn.name))
-        return "pure";
+    // Bare-name externs are pure by default. `//@ impure` externs are method
+    // calls: lift them to statement-level binds so repeated invocations remain
+    // independent. A method call cannot occur in a spec or lambda expression.
+    if (fn.kind === "var") {
+        const ext = ctx.externs.get(fn.name);
+        if (ext) {
+            if (!ext.impure)
+                return "pure";
+            if (ctx.inSpec)
+                throw new Error(`impure extern ${fn.name} cannot be called from a specification`);
+            if (ctx.inLambda)
+                throw new Error(`impure extern ${fn.name} cannot be called from a lambda`);
+            return "method";
+        }
+    }
     if (fn.kind === "var" && lookup(ctx.env, fn.name)?.kind === "fn")
         return "pure";
     if (fn.kind === "var" && ctx.inSpec) {
@@ -848,15 +857,23 @@ function resolveExpr(e, ctx) {
             }
             // Extern dispatch: `NS.method(args)` where NS.method is declared via
             // `//@ extern`. Rewrite into a flat-name call (`NS_method(args)`) so the
-            // rest of the pipeline sees an ordinary pure function. The extern's
-            // declaration is emitted alongside the file as `function {:axiom} ...`.
+            // rest of the pipeline sees an ordinary named call. Pure externs remain
+            // expressions; `//@ impure` externs are lifted as method calls.
             if (e.fn.kind === "field" && e.fn.obj.kind === "var") {
                 const qualified = `${e.fn.obj.name}.${e.fn.field}`;
                 const ext = ctx.externs.get(qualified);
                 if (ext) {
+                    if (ext.impure && ctx.inSpec)
+                        throw new Error(`impure extern ${qualified} cannot be called from a specification`);
+                    if (ext.impure && ctx.inLambda)
+                        throw new Error(`impure extern ${qualified} cannot be called from a lambda`);
                     const args = e.args.map(a => resolveExpr(a, ctx));
                     const fn = { kind: "var", name: ext.flat, ty: { kind: "unknown" } };
-                    return { kind: "call", fn, args, ty: ext.returnTy, callKind: "pure", paramTys: ext.params };
+                    return {
+                        kind: "call", fn, args, ty: ext.returnTy,
+                        callKind: ext.impure ? "method" : "pure",
+                        paramTys: ext.params,
+                    };
                 }
             }
             const fn = resolveExpr(e.fn, ctx);
@@ -1618,8 +1635,33 @@ function collectCallsStmts(stmts, fns, out) {
         }
     }
 }
-function computePureFns(functions) {
+/** Dotted/bare spelling of a raw call target, when statically named. */
+function rawCalleeName(e) {
+    if (e.kind === "var")
+        return e.name;
+    if (e.kind === "field") {
+        const obj = rawCalleeName(e.obj);
+        return obj ? `${obj}.${e.field}` : null;
+    }
+    return null;
+}
+/** Whether a raw function body invokes any extern marked `//@ impure`. */
+function containsImpureExternCall(v, names) {
+    if (Array.isArray(v))
+        return v.some(x => containsImpureExternCall(x, names));
+    if (v === null || typeof v !== "object")
+        return false;
+    const node = v;
+    if (node.kind === "call" && node.fn) {
+        const callee = rawCalleeName(node.fn);
+        if (callee && names.has(callee))
+            return true;
+    }
+    return Object.values(v).some(x => containsImpureExternCall(x, names));
+}
+function computePureFns(functions, externDecls) {
     const allFnNames = new Set(functions.map(fn => fn.name));
+    const impureExternNames = new Set(externDecls.filter(ext => ext.impure).flatMap(ext => [ext.qualified, ext.flat]));
     // //@ pure functions are always considered pure — never taint callers
     const forcePure = new Set(functions.filter(fn => fn.pure).map(fn => fn.name));
     // Build call graph: fn → set of same-file functions it calls
@@ -1630,7 +1672,9 @@ function computePureFns(functions) {
         callGraph.set(fn.name, calls);
     }
     // Seed: syntactically non-pure functions (skip //@ pure)
-    const nonPure = new Set(functions.filter(fn => !forcePure.has(fn.name) && !isSyntacticallyPure(fn.body)).map(fn => fn.name));
+    const nonPure = new Set(functions.filter(fn => !forcePure.has(fn.name) &&
+        (!isSyntacticallyPure(fn.body) || containsImpureExternCall(fn.body, impureExternNames)))
+        .map(fn => fn.name));
     // Build reverse graph: fn → set of functions that call it
     const callers = new Map();
     for (const name of allFnNames)
@@ -1763,7 +1807,7 @@ function precomputeFieldTypesInner(typeDecls) {
 export function resolveModule(raw) {
     _warnedRefEq.clear();
     precomputeFieldTypes(raw.typeDecls);
-    const pureFns = computePureFns(raw.functions);
+    const pureFns = computePureFns(raw.functions, raw.externs ?? []);
     // Pre-compute function parameter and return types
     const fnParams = new Map();
     const fnReturns = new Map();
@@ -1783,7 +1827,7 @@ export function resolveModule(raw) {
     for (const ext of raw.externs ?? []) {
         const params = ext.params.map(p => parseTsType(p.tsType));
         const returnTy = parseTsType(ext.returnType);
-        externs.set(ext.qualified, { flat: ext.flat, params, returnTy });
+        externs.set(ext.qualified, { flat: ext.flat, params, returnTy, impure: ext.impure });
         if (!ext.qualified.includes("."))
             fnReturns.set(ext.qualified, returnTy);
     }
@@ -1821,6 +1865,7 @@ export function resolveModule(raw) {
             returnTy: sig.returnTy,
             requires,
             ensures,
+            impure: ext.impure,
         };
     });
     const emptyCtx = { env: null, typeDecls: raw.typeDecls, overrides: new Map(), allowResult: false, returnTy: { kind: "int" }, pureFns, fnParams, fnReturns, externs, inSpec: false, inLambda: false, narrowedPaths: [], narrowedIndices: [] };

package/tools/dist/transform.js

@@ -2508,10 +2508,10 @@ export function transformModule(mod, specImport, moduleBaseOverride) {
     // Lean module base — overridable via `//@ lean-module` (see lsc.ts). Only the
     // def→types import below reads it; Dafny never passes an override.
     const moduleBase = moduleBaseOverride ?? base;
-    // Externs: emit as top-of-file `function {:axiom}` (Dafny) declarations.
-    // Any `requires`/`ensures` from the source declaration come along so callers
-    // see the same spec the source itself verified. Substitute `\result` with the
-    // function call (same pattern as for in-file pure-function ensures).
+    // Externs: pure declarations become uninterpreted functions; `//@ impure`
+    // declarations become body-less methods so calls have independent results.
+    // Contracts come along in either case. A pure extern's `\result` denotes its
+    // application; an impure extern keeps `\result` for the method out-parameter.
     const externDecls = (mod.externs ?? []).map(ext => {
         const fnCall = { kind: "app", fn: ext.flat, args: ext.params.map(p => ({ kind: "var", name: p.name })) };
         return {
@@ -2521,7 +2521,10 @@ export function transformModule(mod, specImport, moduleBaseOverride) {
             params: ext.params.map(p => ({ name: p.name, type: p.ty })),
             returnType: ext.returnTy,
             requires: ext.requires.map(transformExpr),
-            ensures: ext.ensures.map(e => replaceVar(transformExpr(e), "\\result", fnCall)),
+            ensures: ext.ensures.map(e => ext.impure
+                ? transformExpr(e)
+                : replaceVar(transformExpr(e), "\\result", fnCall)),
+            impure: ext.impure,
         };
     });
     // Def file: Velvet methods