A verification toolchain for TypeScript. Write ordinary TypeScript with //@ specification annotations. The toolchain generates verifiable code from your TypeScript — either in Dafny or Lean 4 (with Velvet 2).
See SPEC.md, DESIGN.md, and GETTING_STARTED.md.
For changes to LemmaScript itself, see CONTRIBUTING.md.
This is a Tech Preview: the core idea is there, but support, semantics, and ergonomics are still evolving.
See our blog post.
See the examples and case studies for verified TypeScript programs, libraries, and apps.
Prerequisites: Node.js >= 18. For the Lean backend: elan. For the Dafny backend: Dafny >= 4.x.
Install from npm:
npm install -g lemmascriptOr from source:
git clone https://github.com/midspiral/LemmaScript.git
cd LemmaScript && npm install && npm run buildLean backend: from the LemmaScript source checkout, clone Velvet 2 as a sibling on the lemma2 branch:
git clone --branch lemma2 https://github.com/namin/velvet.git ../velvet
lake buildFor an existing Velvet checkout, select the branch with:
git -C ../velvet fetch origin
git -C ../velvet checkout lemma2The lemma branch is for the previous Velvet version. Use the Lean version pinned in lean-toolchain (currently 4.34.0); Lake resolves the Mathlib dependency. Velvet 2 does not require a Loom checkout or external Z3/cvc5 binaries. See SPEC_LEAN.md for the project layout and proof workflow.
lsc gen --backend=dafny src/myModule.ts
lsc check --backend=dafny src/myModule.ts
lsc regen --backend=dafny src/myModule.tsWith 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.
lsc gen --backend=lean src/myModule.ts
lake buildlsc claimcheck forwards to lemmascript-claimcheck to sanity check the natural language //@ contract against the formal specifications.
lsc guard forwards to lemmascript-guard to generate a sibling *.guarded.ts module that checks //@ requires at runtime. Import its wrappers at application boundaries.
LemmaScript ships a reusable GitHub Actions workflow that regenerates your artifacts, verifies them, and fails the build if any committed generated file is out of date. Call it from your own repo's workflow:
# .github/workflows/lemmascript.yml
name: LemmaScript
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
verify:
uses: midspiral/LemmaScript/.github/workflows/verify.yml@main
with:
backend: dafny # dafny | lean | dafny-slowThe workflow installs the toolchain and (per backend) the Dafny or Lean stack, then runs tools/check.sh, which batches over a LemmaScript-files.txt at your repo root. This file is the list of sources CI verifies — you create and maintain it. One entry per line, filepath [timeout] [extra dafny flags…]:
src/domain.ts
src/patch.ts 120
src/heavy.ts 300 --isolate-assertions
The optional second column is a per-file timeout in seconds; anything after it is passed verbatim to Dafny. The same list drives lsc check locally when you run it with no file argument, so CI and your local runs verify exactly the same set. To verify additional Dafny files outside that list, add an executable check-extra.sh at the root and it runs automatically (Dafny backends only).
Inputs (all optional):
| Input | Default | Purpose |
|---|---|---|
backend |
dafny |
dafny, lean, or dafny-slow (isolate-assertions / long-running proofs) |
node-version |
24 |
Node.js version |
ls-ref |
main |
LemmaScript ref to verify against |
typecheck |
true |
Run npm ci && npm run typecheck in the calling repo first |
To verify against both backends, add a second job with backend: lean.
Examples:
- talktimer-lemmascript — Dafny-only.
- pi-lemmascript — Dafny + Lean (two jobs).
//@ requires arr.length > 0
//@ ensures \result >= -1 && \result < arr.length
//@ invariant 0 <= i && i <= arr.length
//@ decreases arr.length - i
//@ type i natFor the full surface, see SPEC.md.
| File | Generated? | Purpose |
|---|---|---|
| .ts | — | TypeScript source with //@ annotations |
| .dfy.gen | Yes | Generated Dafny (merge base, always regeneratable) |
| .dfy | Yes (initial) | Annotated Dafny (gen + proof additions) |
| File | Generated? | Purpose |
|---|---|---|
| .ts | — | TypeScript source with //@ annotations |
| .types.lean | Yes | Lean types, namespace Pure defs |
| .spec.lean | No | Ghost definitions, helper lemmas |
| .def.lean | Yes | Velvet method definitions |
| .proof.lean | No | prove_correct with proof tactics |