lemmascript 0.5.22 → 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.5.22",
+  "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)}`);
@@ -1583,10 +1593,8 @@ export function emitDafnyFile(file, tsFileName, opts) {
     // skipped when the corresponding pure def was actually emitted.
     const emittedPureDefs = new Set();
     // Emit a decl, rolling back any preamble requirements it registered if it
-    // throws. A skipped decl must contribute neither text nor preambles — else a
-    // side-effecting `needPreamble` from a half-emitted decl leaves an unused
-    // preamble (e.g. `type Unknown` from a skipped const whose head is
-    // `unknown`-typed but whose value expr is unsupported).
+    // throws, so callers that catch an emission error never observe partial
+    // emitter state.
     const emitDeclTx = (d) => {
         const saved = new Set(_neededPreambles);
         try {
@@ -1601,13 +1609,12 @@ export function emitDafnyFile(file, tsFileName, opts) {
     };
     // Emit declarations
     const declLines = [];
-    const skipped = [];
     for (const decl of file.decls) {
         if (decl.kind === "method" && emittedPureDefs.has(decl.name))
             continue;
         if (decl.kind === "namespace") {
-            // Emit each inner decl individually — if one fails, the rest survive
-            // and failed defs fall back to their method wrappers
+            // Emit each inner declaration separately so failures name the exact
+            // pure declaration that could not be translated.
             for (const inner of decl.decls) {
                 try {
                     declLines.push("");
@@ -1617,10 +1624,9 @@ export function emitDafnyFile(file, tsFileName, opts) {
                 }
                 catch (e) {
                     const name = "name" in inner ? inner.name : "unknown";
-                    const msg = e.message;
-                    console.error(`WARNING: skipping pure '${name}': ${msg}`);
-                    declLines.push(`\n// LemmaScript: skipped pure ${name}`);
-                    skipped.push(name);
+                    const reason = e instanceof Error ? e.message : String(e);
+                    const source = tsFileName ? ` in ${tsFileName}` : "";
+                    throw new Error(`Dafny emission failed for '${name}'${source}: ${reason}`);
                 }
             }
             continue;
@@ -1633,15 +1639,11 @@ export function emitDafnyFile(file, tsFileName, opts) {
         }
         catch (e) {
             const name = "name" in decl ? decl.name : "unknown";
-            const msg = e.message;
-            console.error(`WARNING: skipping '${name}': ${msg}`);
-            declLines.push(`// LemmaScript: skipped ${name}`);
-            skipped.push(name);
+            const reason = e instanceof Error ? e.message : String(e);
+            const source = tsFileName ? ` in ${tsFileName}` : "";
+            throw new Error(`Dafny emission failed for '${name}'${source}: ${reason}`);
         }
     }
-    if (skipped.length > 0) {
-        console.error(`WARNING: ${skipped.length} declaration(s) skipped: ${skipped.join(", ")}`);
-    }
     // Build output with needed preambles
     const lines = [];
     if (tsFileName)

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();
@@ -2158,7 +2170,8 @@ export function extractModule(sourceFile) {
                             });
                         }
                         catch (e) {
-                            console.error(`WARNING: skipping const '${decl.getName()}': ${e.message}`);
+                            const reason = e instanceof Error ? e.message : String(e);
+                            throw new Error(`Failed to extract const '${decl.getName()}' at ${sourceFile.getBaseName()}:${decl.getStartLineNumber()}: ${reason}`);
                         }
                     }
                 }
@@ -2234,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`
@@ -2276,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/lsc.js

@@ -337,4 +337,10 @@ function runFile(cmd, filePath, backend, timeLimit, extraFlags, noVerify = false
     console.error(`Unknown command: ${cmd}`);
     process.exit(1);
 }
-main();
+try {
+    main();
+}
+catch (e) {
+    console.error(`ERROR: ${e instanceof Error ? e.message : String(e)}`);
+    process.exitCode = 1;
+}

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/specparser.js

@@ -4,11 +4,11 @@
  */
 import { normalizeBigIntLiteral } from "./rawir.js";
 const MULTI_OPS = ["<==>", "==>", "===", "!==", "==", "!=", ">=", "<=", "&&", "||"];
-/** Hex / binary / octal / decimal integer, with optional numeric separators and
- *  an optional `n` (BigInt) suffix in capture group 1. Deliberately integer-only:
- *  a trailing `.` is left for the tokenizer to emit as punctuation, exactly as
- *  the previous digit-scanning loop did. */
-const INTEGER_LITERAL = /^(?:(?:0[xX][0-9a-fA-F](?:_?[0-9a-fA-F])*)|(?:0[bB][01](?:_?[01])*)|(?:0[oO][0-7](?:_?[0-7])*)|(?:[0-9](?:_?[0-9])*))(n)?/;
+/** Numeric literals accepted in specs. BigInts are recognized first so their
+ *  exact value never passes through Number; ordinary numbers additionally
+ *  allow TypeScript's fractional and exponent forms. */
+const BIGINT_LITERAL = /^(?:(?:0[xX][0-9a-fA-F](?:_?[0-9a-fA-F])*)|(?:0[bB][01](?:_?[01])*)|(?:0[oO][0-7](?:_?[0-7])*)|(?:[0-9](?:_?[0-9])*))n/;
+const NUMBER_LITERAL = /^(?:(?:0[xX][0-9a-fA-F](?:_?[0-9a-fA-F])*)|(?:0[bB][01](?:_?[01])*)|(?:0[oO][0-7](?:_?[0-7])*)|(?:(?:[0-9](?:_?[0-9])*)(?:\.(?:[0-9](?:_?[0-9])*)?)?|\.(?:[0-9](?:_?[0-9])*))(?:[eE][+-]?(?:[0-9](?:_?[0-9])*))?)/;
 function tokenize(input) {
     const tokens = [];
     let i = 0;
@@ -47,15 +47,17 @@ function tokenize(input) {
             tokens.push({ type: "str", value: s });
             continue;
         }
-        if (/[0-9]/.test(input[i])) {
-            const match = input.slice(i).match(INTEGER_LITERAL);
+        if (/[0-9]/.test(input[i]) || (input[i] === "." && /[0-9]/.test(input[i + 1]))) {
+            const rest = input.slice(i);
+            const bigintMatch = rest.match(BIGINT_LITERAL);
+            const match = bigintMatch ?? rest.match(NUMBER_LITERAL);
             if (!match)
                 throw new Error(`Invalid numeric literal at ${i} in: ${input}`);
             const text = match[0];
             i += text.length;
             // The `n` suffix is meaningful, not noise: a BigInt keeps its exact value
             // as a decimal string instead of being rounded into a double.
-            if (match[1] === "n")
+            if (bigintMatch)
                 tokens.push({ type: "bigint", value: normalizeBigIntLiteral(text) });
             else
                 tokens.push({ type: "num", value: Number(text.replace(/_/g, "")) });

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