lemmascript 0.6.0 → 0.6.2

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.2",
   "description": "A verification toolchain for TypeScript — generates Lean 4 or Dafny from annotated TS",
   "type": "module",
   "engines": {

package/tools/dist/config.js

@@ -0,0 +1,236 @@
+/**
+ * LemmaScript project configuration.
+ *
+ * Config is discovered per source file, validated from one registry, then
+ * layered with eligible file directives before consumers see a resolved set.
+ * Filesystem policy stays here/lsc.ts; extractors and emitters receive options.
+ */
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+export const OPTION_SPECS = {
+    "extern-default": {
+        type: "enum",
+        values: ["pure", "impure"],
+        default: "pure",
+        fileOverride: true,
+        description: "Default model for externs without //@ pure or //@ impure.",
+    },
+    "safe-slice": {
+        type: "boolean",
+        default: false,
+        fileOverride: true,
+        directiveAliases: ["safe-slice"],
+        description: "Use JavaScript-clamping semantics for two-argument array slice.",
+    },
+    "proof-dir": {
+        type: "path",
+        default: null,
+        fileOverride: false,
+        description: "Directory for Dafny artifacts, relative to lemmascript.json.",
+    },
+};
+export const DEFAULT_OPTIONS = Object.freeze(Object.fromEntries(Object.entries(OPTION_SPECS).map(([key, spec]) => [key, spec.default])));
+const KNOWN_KEYS = Object.keys(OPTION_SPECS);
+const CONFIG_CACHE = new Map();
+function fail(source, message) {
+    throw new Error(`${source}: ${message}`);
+}
+function isKnownKey(key) {
+    return Object.hasOwn(OPTION_SPECS, key);
+}
+function parseValue(key, raw, source) {
+    const spec = OPTION_SPECS[key];
+    if (spec.type === "boolean") {
+        if (typeof raw !== "boolean")
+            fail(source, `option '${key}' must be true or false`);
+        return raw;
+    }
+    if (spec.type === "enum") {
+        if (typeof raw !== "string" || !spec.values.includes(raw)) {
+            fail(source, `option '${key}' must be one of: ${spec.values.join(", ")}`);
+        }
+        return raw;
+    }
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        fail(source, `option '${key}' must be a non-empty relative path`);
+    }
+    if (path.isAbsolute(raw))
+        fail(source, `option '${key}' must be relative to lemmascript.json`);
+    return raw;
+}
+/** Validate a parsed lemmascript.json object, returning only explicitly set keys. */
+export function validateOptions(raw, source) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        fail(source, "expected a JSON object");
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (key === "$schema")
+            continue;
+        if (!isKnownKey(key)) {
+            fail(source, `unknown option '${key}' (known options: ${KNOWN_KEYS.join(", ")})`);
+        }
+        out[key] = parseValue(key, value, source);
+    }
+    return out;
+}
+/** Last line in the leading-comment region. Directives after code are errors. */
+function leadingCommentLineCount(lines) {
+    let inBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        let rest = lines[i];
+        if (i === 0)
+            rest = rest.replace(/^\uFEFF/, "");
+        if (i === 0 && rest.startsWith("#!"))
+            continue;
+        while (true) {
+            rest = rest.trimStart();
+            if (inBlock) {
+                const end = rest.indexOf("*/");
+                if (end < 0)
+                    break;
+                inBlock = false;
+                rest = rest.slice(end + 2);
+                continue;
+            }
+            if (rest.length === 0 || rest.startsWith("//"))
+                break;
+            if (rest.startsWith("/*")) {
+                const end = rest.indexOf("*/", 2);
+                if (end < 0) {
+                    inBlock = true;
+                    break;
+                }
+                rest = rest.slice(end + 2);
+                continue;
+            }
+            return i;
+        }
+    }
+    return lines.length;
+}
+function parseDirectiveValue(key, text, source) {
+    const spec = OPTION_SPECS[key];
+    if (spec.type === "boolean") {
+        if (text !== "true" && text !== "false")
+            fail(source, `option '${key}' must be true or false`);
+        return (text === "true");
+    }
+    if (spec.type === "enum")
+        return parseValue(key, text, source);
+    // Config-only today, but keep the diagnostic precise if a future path is
+    // made file-overridable.
+    return parseValue(key, text, source);
+}
+/** Parse top-of-file `//@ option key value` directives and legacy aliases. */
+export function parseFileOptions(sourceText, source) {
+    const lines = sourceText.split(/\r?\n/);
+    const leadingLines = leadingCommentLineCount(lines);
+    const seen = new Map();
+    const out = {};
+    const setOption = (key, value, line) => {
+        const previous = seen.get(key);
+        if (previous !== undefined) {
+            fail(`${source}:${line}`, `duplicate option '${key}' (first set on line ${previous})`);
+        }
+        seen.set(key, line);
+        out[key] = value;
+    };
+    const parseLine = (lineText, index, inLeadingRegion) => {
+        const line = index + 1;
+        const optionMatch = lineText.match(/^[ \t]*\/\/@[ \t]+option(?:[ \t]+(.*?))?[ \t]*$/);
+        if (optionMatch) {
+            if (!inLeadingRegion)
+                fail(`${source}:${line}`, "//@ option directives must appear before the first source statement");
+            const parts = (optionMatch[1] ?? "").trim().split(/\s+/).filter(Boolean);
+            if (parts.length !== 2)
+                fail(`${source}:${line}`, "expected //@ option <key> <value>");
+            const [rawKey, rawValue] = parts;
+            if (!isKnownKey(rawKey)) {
+                fail(`${source}:${line}`, `unknown option '${rawKey}' (known options: ${KNOWN_KEYS.join(", ")})`);
+            }
+            const spec = OPTION_SPECS[rawKey];
+            if (!spec.fileOverride)
+                fail(`${source}:${line}`, `option '${rawKey}' is config-only`);
+            setOption(rawKey, parseDirectiveValue(rawKey, rawValue, `${source}:${line}`), line);
+            return;
+        }
+        const aliasMatch = lineText.match(/^[ \t]*\/\/@[ \t]+([A-Za-z][A-Za-z0-9-]*)[ \t]*$/);
+        if (!aliasMatch)
+            return;
+        const alias = aliasMatch[1];
+        for (const key of KNOWN_KEYS) {
+            const aliases = "directiveAliases" in OPTION_SPECS[key]
+                ? OPTION_SPECS[key].directiveAliases
+                : [];
+            if (!aliases.includes(alias))
+                continue;
+            // Legacy aliases retain their pre-config placement behavior. New generic
+            // option directives are deliberately restricted to the file preamble.
+            setOption(key, true, line);
+            return;
+        }
+    };
+    for (let i = 0; i < lines.length; i++)
+        parseLine(lines[i], i, i < leadingLines);
+    return out;
+}
+/** Apply defaults and all cross-option rules after explicit layers are merged. */
+export function resolveOptions(explicit, source) {
+    // There are no cross-option constraints in the initial registry. Keep this
+    // as the single resolution gate: future dependent defaults (UTF-16 → local
+    // Dafny library) and incompatibilities belong here, before any consumer runs.
+    void source;
+    return Object.freeze({ ...DEFAULT_OPTIONS, ...explicit });
+}
+/** Find `fileName` at or above `fromPath`. */
+export function findUp(fileName, fromPath, fromIsDirectory = false) {
+    let dir = fromIsDirectory ? path.resolve(fromPath) : path.dirname(path.resolve(fromPath));
+    while (true) {
+        const candidate = path.join(dir, fileName);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** Discover, parse, and validate a config without materializing defaults. */
+export function loadConfigOptions(sourcePath, configPath) {
+    const configFile = configPath ? path.resolve(configPath) : findUp("lemmascript.json", sourcePath);
+    if (!configFile)
+        return { explicit: {}, configFile: null };
+    if (!existsSync(configFile))
+        fail(configFile, "config file not found");
+    const cached = CONFIG_CACHE.get(configFile);
+    if (cached)
+        return { explicit: { ...cached }, configFile };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(configFile, "utf8"));
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        fail(configFile, `invalid JSON (${detail})`);
+    }
+    const explicit = validateOptions(parsed, configFile);
+    CONFIG_CACHE.set(configFile, explicit);
+    return { explicit: { ...explicit }, configFile };
+}
+/** Resolve the directory containing one source file's Dafny companions. */
+export function resolveDafnyArtifactDir(sourcePath, configFile, options) {
+    const source = path.resolve(sourcePath);
+    const proofDir = options["proof-dir"];
+    if (proofDir === null)
+        return path.dirname(source);
+    if (!configFile)
+        fail(source, "proof-dir requires a lemmascript.json file");
+    const configDir = path.dirname(path.resolve(configFile));
+    const relativeSource = path.relative(configDir, source);
+    if (relativeSource === ".." || relativeSource.startsWith(`..${path.sep}`) || path.isAbsolute(relativeSource)) {
+        fail(source, `is outside the config directory ${configDir}; cannot map proof-dir`);
+    }
+    const proofRoot = path.resolve(configDir, proofDir);
+    return path.join(proofRoot, path.dirname(relativeSource));
+}

package/tools/dist/dafny-emit.js

@@ -4,6 +4,7 @@
 import { exactIntegerLiteral, usesName, usesNameInDecl, usesNameInStmts } from "./ir.js";
 import { freshNameWhere, userNames } from "./names.js";
 import { renameFreeVar } from "./transform.js";
+import { DEFAULT_OPTIONS } from "./config.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. */
@@ -189,12 +190,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 +994,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)}`);
@@ -1015,10 +1026,8 @@ function emitDecl(d) {
 /** Preamble tracking — emitters add keys via `needPreamble(key)`, emitDafnyFile emits them. */
 const _neededPreambles = new Set();
 function needPreamble(key) { _neededPreambles.add(key); }
-/** File-level opt-in for JS-clamp semantics on `arr.slice(lo, hi)`. Set by
- *  `emitDafnyFile` from the `//@ safe-slice` directive; consulted by the
- *  array-method emit. Off by default — case studies that wrote their `.slice`
- *  calls with provable bounds get direct `s[lo..hi]` emission. */
+/** Effective JS-clamp semantics for `arr.slice(lo, hi)`, resolved from project
+ *  config plus file directives before emission. */
 let _useSafeSlice = false;
 const POW2 = `function Pow2(n: int): int
   requires n >= 0
@@ -1572,8 +1581,8 @@ function translatePattern(p) {
         return ctorName;
     return `${ctorName}(${p.binders.map(escapeName).join(", ")})`;
 }
-export function emitDafnyFile(file, tsFileName, opts) {
-    _useSafeSlice = !!opts?.safeSlice;
+export function emitDafnyFile(file, tsFileName, options = DEFAULT_OPTIONS) {
+    _useSafeSlice = options["safe-slice"];
     resetDafnyNameCache();
     buildRecordCtorMap(file.decls);
     _neededPreambles.clear();

package/tools/dist/extract.js

@@ -8,6 +8,7 @@ import { Project, Node, SyntaxKind, ScriptTarget, ts } from "ts-morph";
 import { initTypeParser } from "./types.js";
 import { normalizeBigIntLiteral } from "./rawir.js";
 import { setUserNames, freshName } from "./names.js";
+import { DEFAULT_OPTIONS } from "./config.js";
 // ── Expression extraction ────────────────────────────────────
 /** When set, calls whose function/method name matches this key are replaced with havoc. */
 let _havocKey = null;
@@ -32,7 +33,9 @@ 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>`
+ *  when effectively pure, or as a body-less method when effectively impure
+ *  after project defaults and source overrides.
  *  Cleared at the start of every `extractModule`. */
 const _externs = new Map();
 /** Signature types of *kept* externs, for the imported-type resolver: a type
@@ -50,6 +53,8 @@ let _currentSourceFile = null;
  *  that no verified function actually calls — and whose TS return types
  *  often don't translate to valid Dafny. */
 let _inFunctionExtraction = false;
+/** Effective options for the current extraction. Reset at extractModule entry. */
+let _extractOptions = DEFAULT_OPTIONS;
 /** Counter for synthetic names used by let-statement array destructuring
  *  when the initializer isn't a bare variable (single-eval temp). */
 let _destrCounter = 0;
@@ -163,7 +168,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 = externIsImpure(externalDecl, qualified);
+    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 +767,61 @@ 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);
+}
+function enclosingVariableStatement(node) {
+    let current = node.getParent();
+    while (current && !Node.isSourceFile(current)) {
+        if (Node.isVariableStatement(current))
+            return current;
+        current = current.getParent();
+    }
+    return undefined;
+}
+/** `pure`/`impure` may be attached to a function, its first statement, or the
+ *  variable statement that owns a const arrow. */
+function hasExternModeAnnotation(node, keyword, parentStmt) {
+    if (hasBareFunctionAnnotation(node, keyword))
+        return true;
+    if (Node.isVariableDeclaration(node)) {
+        const init = node.getInitializer();
+        if (init && Node.isArrowFunction(init) && hasBareFunctionAnnotation(init, keyword))
+            return true;
+    }
+    const statement = parentStmt ?? enclosingVariableStatement(node);
+    return !!statement && statement.getLeadingCommentRanges()
+        .some(r => r.getText().trim() === `//@ ${keyword}`);
+}
+function externIsImpure(node, name, parentStmt) {
+    const pure = hasExternModeAnnotation(node, "pure", parentStmt);
+    const impure = hasExternModeAnnotation(node, "impure", parentStmt);
+    if (pure && impure)
+        throw new Error(`${name}: extern cannot be both //@ pure and //@ impure`);
+    if (impure)
+        return true;
+    if (pure)
+        return false;
+    return _extractOptions["extern-default"] === "impure";
+}
 // ── Type declaration extraction ──────────────────────────────
 function extractTypeDecl(decl, extraDecls) {
     const name = decl.getName();
@@ -2016,7 +2066,8 @@ function extractFunctionInner(fn, parentAnnotations) {
     };
 }
 // ── Module extraction ────────────────────────────────────────
-export function extractModule(sourceFile) {
+export function extractModule(sourceFile, options = DEFAULT_OPTIONS) {
+    _extractOptions = options;
     // 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())));
@@ -2277,7 +2328,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: externIsImpure(f.node, qualified, f.parentStmt),
+        });
     }
     // 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/info-command.js

@@ -83,7 +83,7 @@ function typedFn(fn, rawFn) {
         bodyKinds: bodyKinds(fn),
     };
 }
-export function runTypedInfo(raw, typed, version, backendDirective, dafny) {
+export function runTypedInfo(raw, typed, version, backendDirective, options, dafny) {
     const rawByName = new Map(raw.functions.map(f => [f.name, f]));
     const rawMethods = new Map(raw.classes.flatMap(c => c.methods.map(m => [`${c.name}.${m.name}`, m])));
     const out = {
@@ -91,6 +91,7 @@ export function runTypedInfo(raw, typed, version, backendDirective, dafny) {
         lemmascript: version,
         file: typed.file,
         backendDirective,
+        options,
         typeDecls: typed.typeDecls,
         externs: typed.externs,
         constants: typed.constants,

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; add //@ pure to this extern or use extern-default: pure");
+            }
             // 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

@@ -5,7 +5,7 @@
  * Pipeline: extract → resolve → narrow → transform → peephole → emit
  */
 import { Project, ScriptTarget } from "ts-morph";
-import { existsSync, readFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync } from "fs";
 import { execFileSync } from "child_process";
 import { createRequire } from "module";
 import path from "path";
@@ -20,6 +20,7 @@ import { emitDafnyFile, emittedNameMap } from "./dafny-emit.js";
 import { dafnyGen, dafnyCheckDiff, dafnyVerify, dafnyRegen } from "./dafny-commands.js";
 import { leanGen, leanCheck } from "./lean-commands.js";
 import { runInfo, runTypedInfo } from "./info-command.js";
+import { findUp, loadConfigOptions, parseFileOptions, resolveDafnyArtifactDir, resolveOptions, } from "./config.js";
 /** Version of the lemmascript package — the root package.json sits two levels
  *  above this module from both tools/src/ (tsx) and tools/dist/ (installed). */
 function lscVersion() {
@@ -86,6 +87,16 @@ function main() {
         backend = val;
         args.splice(backendIdx, 1);
     }
+    const configIdx = args.findIndex(a => a.startsWith("--config="));
+    let configPath;
+    if (configIdx >= 0) {
+        configPath = args[configIdx].slice("--config=".length);
+        if (!configPath) {
+            console.error("Invalid --config: expected a path after '='");
+            process.exit(1);
+        }
+        args.splice(configIdx, 1);
+    }
     const timeLimitIdx = args.findIndex(a => a.startsWith("--time-limit="));
     let timeLimit;
     if (timeLimitIdx >= 0) {
@@ -139,7 +150,8 @@ function main() {
     }
     const [cmd, filePath] = args;
     if (!cmd) {
-        console.error("Usage: lsc <gen|check|regen|extract|info> [--backend=lean|dafny] <file.ts>");
+        console.error("Usage: lsc <gen|check|regen|extract|info> [--backend=lean|dafny] [--config=path] <file.ts>");
+        console.error("       lsc config [--config=path] [<file.ts>]");
         console.error("       lsc info --typed <file.ts>   (machine-readable Typed IR contract to stdout)");
         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)");
@@ -150,11 +162,15 @@ function main() {
         console.error(`--typed is only valid with the info command (got: ${cmd})`);
         process.exit(1);
     }
+    if (cmd === "config") {
+        runConfig(filePath, configPath);
+        return;
+    }
     if (!filePath) {
-        runBatch(cmd, backend, slow);
+        runBatch(cmd, backend, slow, configPath);
         return;
     }
-    runFile(cmd, filePath, backend, timeLimit, extraFlags, noVerify, typedInfo);
+    runFile(cmd, filePath, backend, timeLimit, extraFlags, noVerify, typedInfo, configPath);
 }
 // LemmaScript-files.txt, parsed: `filepath [timeout_in_seconds] [extra dafny
 // flags…]` per line; no timeout = Dafny default. Exits if the file is absent.
@@ -172,11 +188,36 @@ function readEntries() {
         return { file, timeout, flags };
     });
 }
+function effectiveOptions(sourcePath, sourceText, configPath) {
+    const loaded = loadConfigOptions(sourcePath, configPath);
+    const fileOptions = parseFileOptions(sourceText, sourcePath);
+    const options = resolveOptions({ ...loaded.explicit, ...fileOptions }, sourcePath);
+    return { options, configFile: loaded.configFile };
+}
+/** `lsc config [file.ts]` — report discovery, effective values, and routing. */
+function runConfig(filePath, configPath) {
+    if (!filePath) {
+        // loadConfigOptions starts discovery at a source file's parent, so use a
+        // synthetic path under cwd for the directory-oriented command form.
+        const probe = path.join(process.cwd(), ".lemmascript-config-probe.ts");
+        const loaded = loadConfigOptions(probe, configPath);
+        const options = resolveOptions(loaded.explicit, loaded.configFile ?? process.cwd());
+        console.log(JSON.stringify({ configFile: loaded.configFile, options }, null, 2));
+        return;
+    }
+    const sourcePath = path.resolve(filePath);
+    if (!existsSync(sourcePath))
+        throw new Error(`File not found: ${sourcePath}`);
+    const sourceText = readFileSync(sourcePath, "utf8");
+    const { options, configFile } = effectiveOptions(sourcePath, sourceText, configPath);
+    const artifactDir = resolveDafnyArtifactDir(sourcePath, configFile, options);
+    console.log(JSON.stringify({ configFile, options, artifactDir }, null, 2));
+}
 // 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) {
+function runBatch(cmd, backend, slow, configPath) {
     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);
@@ -184,39 +225,42 @@ function runBatch(cmd, backend, slow) {
     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);
+            runFile("gen-check", e.file, backend, undefined, undefined, false, false, configPath);
         }
         else {
-            runFile(cmd, e.file, backend, e.timeout, e.flags);
+            runFile(cmd, e.file, backend, e.timeout, e.flags, false, false, configPath);
         }
     }
 }
-function runFile(cmd, filePath, backend, timeLimit, extraFlags, noVerify = false, typedInfo = false) {
+function guardRelocatedDafnyProof(sourceDir, artifactDir, base, targetDfyPath) {
+    if (path.resolve(sourceDir) === path.resolve(artifactDir) || existsSync(targetDfyPath))
+        return;
+    const legacyPaths = [
+        path.join(sourceDir, `${base}.dfy`),
+        path.join(sourceDir, `${base}.dfy.base`),
+        path.join(sourceDir, `${base}.dfy.merged`),
+    ].filter(existsSync);
+    if (legacyPaths.length === 0)
+        return;
+    throw new Error(`proof-dir maps '${base}' to ${artifactDir}, but existing proof state would be left behind:\n` +
+        legacyPaths.map(p => `  ${p}`).join("\n") +
+        `\nMove the hand-written .dfy to ${targetDfyPath}, inspect or remove stale .dfy.base/.dfy.merged files, then rerun. The .dfy.gen file is regeneratable.`);
+}
+function runFile(cmd, filePath, backend, timeLimit, extraFlags, noVerify = false, typedInfo = false, configPath) {
     const absPath = path.resolve(filePath);
     if (!existsSync(absPath)) {
         console.error(`File not found: ${absPath}`);
         process.exit(1);
     }
     // Find nearest tsconfig.json for import resolution; fall back to bare options
-    function findTsConfig(from) {
-        let dir = path.dirname(from);
-        while (true) {
-            const candidate = path.join(dir, "tsconfig.json");
-            if (existsSync(candidate))
-                return candidate;
-            const parent = path.dirname(dir);
-            if (parent === dir)
-                return undefined;
-            dir = parent;
-        }
-    }
-    const tsConfigFilePath = findTsConfig(absPath);
+    const tsConfigFilePath = findUp("tsconfig.json", absPath) ?? undefined;
     const project = tsConfigFilePath
         ? new Project({ tsConfigFilePath })
         : new Project({ compilerOptions: { strict: true, target: ScriptTarget.ESNext, lib: ["lib.esnext.d.ts"] } });
     const sourceFile = project.addSourceFileAtPath(absPath);
     project.resolveSourceFileDependencies();
     const fullText = sourceFile.getFullText();
+    const { options, configFile } = effectiveOptions(absPath, fullText, configPath);
     // Check //@ backend directive — skip if backend doesn't match.
     // `extract` and `info` are backend-neutral and always run.
     const backendDirective = fullText.match(/\/\/@ backend (\w+)/);
@@ -224,8 +268,6 @@ function runFile(cmd, filePath, backend, timeLimit, extraFlags, noVerify = false
         console.log(`Skipped: ${path.basename(filePath)} (//@ backend ${backendDirective[1]}, current: ${backend})`);
         return;
     }
-    // File-level directives consumed by the Dafny emitter.
-    const safeSlice = /\/\/@ safe-slice\b/.test(fullText);
     // `//@ lean-module <name>` overrides the Lean module base (default: file
     // basename). Lean module names are flat/global, so two identically-named
     // `.ts` files (e.g. an in-place fork's duplicated `compaction.ts`) would emit
@@ -234,7 +276,7 @@ function runFile(cmd, filePath, backend, timeLimit, extraFlags, noVerify = false
     const leanModuleDirective = fullText.match(/\/\/@ lean-module ([A-Za-z0-9_.\-]+)/);
     const leanModuleOverride = leanModuleDirective ? leanModuleDirective[1] : undefined;
     // Extract: ts-morph → Raw IR
-    const raw = extractModule(sourceFile);
+    const raw = extractModule(sourceFile, options);
     if (cmd === "extract") {
         console.log(JSON.stringify(raw, null, 2));
         return;
@@ -263,13 +305,13 @@ function runFile(cmd, filePath, backend, timeLimit, extraFlags, noVerify = false
                 typesFile = peepholeModule(typesFile, "dafny");
             defFile = peepholeModule(defFile, "dafny");
             const merged = { ...defFile, decls: [...(typesFile?.decls ?? []), ...defFile.decls] };
-            emitDafnyFile(merged, path.basename(filePath), { safeSlice });
+            emitDafnyFile(merged, path.basename(filePath), options);
             dafnyInfo = { emittedNames: Object.fromEntries(emittedNameMap()) };
         }
         catch (err) {
             dafnyInfo = { error: err instanceof Error ? err.message : String(err) };
         }
-        runTypedInfo(raw, typed, lscVersion(), backendDirective ? backendDirective[1] : null, dafnyInfo);
+        runTypedInfo(raw, typed, lscVersion(), backendDirective ? backendDirective[1] : null, options, dafnyInfo);
         return;
     }
     const dir = path.dirname(absPath);
@@ -282,10 +324,13 @@ function runFile(cmd, filePath, backend, timeLimit, extraFlags, noVerify = false
         defFile = peepholeModule(defFile, "dafny");
         const allDecls = [...(typesFile?.decls ?? []), ...defFile.decls];
         const merged = { ...defFile, decls: allDecls };
-        const text = emitDafnyFile(merged, path.basename(filePath), { safeSlice });
-        const genPath = path.join(dir, `${base}.dfy.gen`);
-        const dfyPath = path.join(dir, `${base}.dfy`);
-        const basePath = path.join(dir, `${base}.dfy.base`);
+        const text = emitDafnyFile(merged, path.basename(filePath), options);
+        const artifactDir = resolveDafnyArtifactDir(absPath, configFile, options);
+        const genPath = path.join(artifactDir, `${base}.dfy.gen`);
+        const dfyPath = path.join(artifactDir, `${base}.dfy`);
+        const basePath = path.join(artifactDir, `${base}.dfy.base`);
+        guardRelocatedDafnyProof(dir, artifactDir, base, dfyPath);
+        mkdirSync(artifactDir, { recursive: true });
         if (cmd === "gen") {
             dafnyGen(genPath, dfyPath, text);
             return;
@@ -300,12 +345,12 @@ function runFile(cmd, filePath, backend, timeLimit, extraFlags, noVerify = false
             dafnyGen(genPath, dfyPath, text);
             if (!dafnyCheckDiff(genPath, dfyPath))
                 process.exit(1);
-            if (!dafnyVerify(dfyPath, dir, timeLimit, extraFlags))
+            if (!dafnyVerify(dfyPath, artifactDir, timeLimit, extraFlags))
                 process.exit(1);
             return;
         }
         if (cmd === "regen") {
-            dafnyRegen(genPath, dfyPath, basePath, text, dir, timeLimit, extraFlags, noVerify);
+            dafnyRegen(genPath, dfyPath, basePath, text, artifactDir, timeLimit, extraFlags, noVerify);
             return;
         }
         console.error(`Unknown command: ${cmd}`);

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";
+    // Effectively pure bare-name externs are function calls. Impure externs are
+    // lifted to statement-level method 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 resolved as 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: effectively pure declarations become uninterpreted functions;
+    // impure declarations become body-less methods with 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