{"id":48048591,"url":"https://github.com/e6qu/rust-lean-aeneas","last_synced_at":"2026-04-04T14:19:40.863Z","repository":{"id":346228467,"uuid":"1188375100","full_name":"e6qu/rust-lean-aeneas","owner":"e6qu","description":"Comprehensive tutorial series: formal verification of Rust programs using Lean 4 and Aeneas — from arithmetic proofs to a verified multi-agent LLM harness","archived":false,"fork":false,"pushed_at":"2026-03-22T22:18:37.000Z","size":516,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-23T14:58:19.539Z","etag":null,"topics":["aeneas","formal-verification","lean4","llm-agents","rust","theorem-proving","tui","tutorial"],"latest_commit_sha":null,"homepage":null,"language":"Lean","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/e6qu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-22T01:36:28.000Z","updated_at":"2026-03-22T22:18:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/e6qu/rust-lean-aeneas","commit_stats":null,"previous_names":["e6qu/rust-lean-aeneas"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/e6qu/rust-lean-aeneas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e6qu%2Frust-lean-aeneas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e6qu%2Frust-lean-aeneas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e6qu%2Frust-lean-aeneas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e6qu%2Frust-lean-aeneas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/e6qu","download_url":"https://codeload.github.com/e6qu/rust-lean-aeneas/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e6qu%2Frust-lean-aeneas/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31402296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aeneas","formal-verification","lean4","llm-agents","rust","theorem-proving","tui","tutorial"],"created_at":"2026-04-04T14:19:40.765Z","updated_at":"2026-04-04T14:19:40.839Z","avatar_url":"https://github.com/e6qu.png","language":"Lean","readme":"# Rust + Lean 4 Formal Verification via Aeneas\n\nA comprehensive, beginner-friendly tutorial series that teaches **formal verification of Rust programs** using **Lean 4** and **Aeneas**. The series culminates in a fully verified TUI multi-agent LLM harness.\n\n\u003e **235 files | 32,800+ lines of code | 297 tests | 11 tutorials**\n\u003e\n\u003e Rust code + Lean proofs + deep walkthroughs — from \"hello world\" to a verified multi-agent system.\n\n## Motivation\n\nSoftware testing checks examples. Formal verification checks *everything*.\n\nA test suite for a sorting function might check 100 inputs and declare success. A formal proof checks all 2^64 possible inputs simultaneously and guarantees the output is sorted and a permutation of the input. No edge case is missed. No corner case is forgotten. The proof *is* the specification, and if the code compiles against it, the code is correct — by mathematical certainty, not by hope.\n\n**Why does this matter now?**\n\n- **LLM agents are becoming critical infrastructure.** When an agent manages your calendar, writes your code, or handles your finances, \"it usually works\" isn't good enough. We need mathematical guarantees about agent behavior: that they always terminate, that messages are never lost, that guardrails are never bypassed.\n- **Rust gives us memory safety but not correctness.** A Rust program won't segfault or have data races. But it can still sort wrong, lose messages, or enter impossible states. Formal verification closes this gap.\n- **The tools are finally practical.** Lean 4 is a real programming language (not just a proof assistant). Aeneas translates real Rust code (not toy subsets). The workflow is: write normal Rust, translate automatically, prove properties in Lean. No annotations in your Rust source. No special syntax. No compromise on performance.\n\n**Why this tutorial series?**\n\nMost formal verification resources assume a PhD in type theory. This series assumes you know basic algorithms and nothing else. It builds from `2 + 3 = 5` to proving that a multi-agent LLM orchestrator correctly routes messages, fairly schedules agents, and always terminates within its budget — and every step along the way is explained for a total beginner.\n\n## What This Project Is\n\nThis project demonstrates how to **prove Rust programs correct** — not just that they compile, not just that they pass tests, but that they satisfy precise mathematical specifications for *all possible inputs*.\n\nThe key tools:\n\n- **[Rust](https://www.rust-lang.org/)** — the systems programming language whose type system guarantees memory safety\n- **[Lean 4](https://lean-lang.org/)** — a theorem prover and programming language that can express and verify mathematical proofs\n- **[Aeneas](https://github.com/AeneasVerif/aeneas)** — a tool that translates Rust code into pure functional Lean code, enabling formal proofs about Rust programs\n\n### What gets verified\n\n| Property | Meaning | Example |\n|----------|---------|---------|\n| **No panics** | Function never crashes for any input | `checked_add` handles all `u32` pairs |\n| **Functional correctness** | Output matches mathematical specification | RPN evaluator computes the right answer |\n| **Roundtrip** | Decode(Encode(x)) = x for all x | Message serialization is lossless |\n| **Invariant preservation** | Critical properties always hold | Traffic light never shows green both ways |\n| **Termination** | Program always finishes | Agent loop exits within step budget |\n| **Fairness** | Resources are allocated equitably | Round-robin gives each agent equal turns |\n| **Composition** | Components work correctly together | User message reaches the right agent end-to-end |\n\n## Architecture: Functional Core, Imperative Shell\n\nEvery project in this series follows the same pattern:\n\n```\n┌─────────────────────────────────────────┐\n│         Imperative Shell (I/O)          │  ← NOT verified (terminal, network, files)\n│  ┌───────────────────────────────────┐  │\n│  │       Verified Pure Core          │  │  ← Translated by Aeneas, proved in Lean\n│  │  (state machines, parsers,        │  │\n│  │   protocols, business logic)      │  │\n│  └───────────────────────────────────┘  │\n└─────────────────────────────────────────┘\n```\n\nThe **pure core** contains all the logic that matters — state transitions, data transformations, protocol handling. This is what Aeneas translates and what we prove correct. The **imperative shell** handles I/O (reading the terminal, making HTTP calls) and is intentionally left unverified.\n\n## Prerequisites\n\n- Basic knowledge of algorithms (loops, recursion, data structures)\n- A computer with macOS or Linux\n- Willingness to learn — no prior Lean, formal verification, or advanced Rust knowledge required\n\n## Project Structure\n\n```\nrust-lean-aeneas/\n├── LEAN.md                    Deep reference on Lean 4\n├── AENEAS.md                  Deep reference on Aeneas\n├── PLAN.md                    Master implementation plan\n│\n└── tutorials/\n    ├── 01-setup-hello-proof/       Install tools, first proof\n    ├── 02-rpn-calculator/          Stack machine + correctness proofs\n    ├── 03-infix-calculator/        Parser + equivalence with RPN\n    ├── 04-state-machines/          Generic state machines + invariant proofs\n    ├── 05-message-protocol/        Binary protocol + roundtrip proofs\n    ├── 06-buffer-management/       Ring buffer, gap buffer + data structure proofs\n    ├── 07-tui-core/                Pure TUI model + layout/render proofs\n    ├── 08-llm-client-core/         LLM protocol logic + well-formedness proofs\n    ├── 09-agent-reasoning/         Agent state machine + termination proofs\n    ├── 10-multi-agent-orchestrator/ Multi-agent system + fairness/routing proofs\n    └── 11-full-integration/        Complete verified TUI LLM agent harness\n```\n\n## Tutorial Progression\n\nThe tutorials are designed to be followed in order. Each one introduces new Lean concepts and builds on previous work:\n\n| Tutorial | What You Build | What You Prove | New Concepts |\n|----------|---------------|----------------|--------------|\n| [01](tutorials/01-setup-hello-proof/README.md) | Simple arithmetic functions | No panics, correct results | Curry-Howard, `step` tactic |\n| [02](tutorials/02-rpn-calculator/README.md) | RPN calculator | Stack invariants, evaluator correctness | Inductive types, `cases`, `induction` |\n| [03](tutorials/03-infix-calculator/README.md) | Infix calculator + parser | Parser termination, RPN equivalence | Recursive types, tree induction, `simp` |\n| [04](tutorials/04-state-machines/README.md) | State machine framework | Safety, liveness, mutual exclusion | Traits as structures, `decide` |\n| [05](tutorials/05-message-protocol/README.md) | Binary message protocol | Roundtrip, no message loss | Byte reasoning, `omega` |\n| [06](tutorials/06-buffer-management/README.md) | Ring buffer, gap buffer | Capacity, FIFO, content preservation | Modular arithmetic, loop invariants |\n| [07](tutorials/07-tui-core/README.md) | TUI model (pure) | Layout correctness, render bounds | Widget trees, Rect arithmetic |\n| [08](tutorials/08-llm-client-core/README.md) | LLM client (pure) | Request validity, context window | Trait specs, axioms |\n| [09](tutorials/09-agent-reasoning/README.md) | Agent reasoning engine | Termination, tool safety, guardrails | Decreasing measures, reachability |\n| [10](tutorials/10-multi-agent-orchestrator/README.md) | Multi-agent orchestrator | Routing, fairness, budget, voting | Distributed reasoning, `Finset` |\n| [11](tutorials/11-full-integration/README.md) | Full TUI LLM agent | End-to-end composition, state consistency | Module composition, I/O axioms |\n\n## Dependency Graph\n\n```\n01 Setup\n ↓\n02 RPN Calculator\n ↓\n03 Infix Calculator ←── imports 02 for equivalence proof\n ↓\n04 State Machines ─── KEY BUILDING BLOCK for 07-11\n ↓\n05 Message Protocol ──────────────────────┐\n ↓                                        │\n06 Buffer Management ─────────────┐       │\n ↓                                │       │\n07 TUI Core ←── uses 06           │       │\n ↓                                │       │\n08 LLM Client Core ←── uses 04   │       │\n ↓                                │       │\n09 Agent Reasoning ←── uses 04,08 │       │\n ↓                                │       │\n10 Multi-Agent ←── uses 04,05,09  │       │\n ↓                                ↓       ↓\n11 Full Integration ←── uses 05,06,07,08,09,10\n```\n\n## Quick Start\n\nSee [Tutorial 01: Setup and Hello Proof](tutorials/01-setup-hello-proof/README.md) to get started.\n\n## Reference Documents\n\n- [LEAN.md](LEAN.md) — Everything you need to know about Lean 4\n- [AENEAS.md](AENEAS.md) — Everything you need to know about Aeneas\n\n## Project Documents\n\n- [STATUS.md](STATUS.md) — Current project status and what works/doesn't\n- [PLAN.md](PLAN.md) — Master implementation plan\n- [GAP_ANALYSIS.md](GAP_ANALYSIS.md) — What's missing for real formal verification\n- [DO_NEXT.md](DO_NEXT.md) — Immediate next steps\n- [WHAT_WE_DID.md](WHAT_WE_DID.md) — History of what was built\n\n## How Each Tutorial Works\n\nEvery tutorial (02 and above) has the same structure:\n\n```\ntutorials/NN-name/\n├── README.md          Detailed walkthrough with explanations\n├── PLAN.md            Implementation plan and design decisions\n├── rust/\n│   ├── Cargo.toml     Rust project\n│   └── src/           Rust source code (the verified core)\n└── lean/\n    ├── lakefile.lean   Lean project config\n    ├── lean-toolchain  Lean version\n    └── ...             Generated Lean + hand-written proofs\n```\n\nThe workflow for each tutorial:\n1. Read the README for context and theory\n2. Study the Rust code in `rust/src/`\n3. Run Charon + Aeneas to generate Lean code\n4. Study the generated Lean in `lean/`\n5. Read and understand the hand-written proofs\n6. Try the exercises\n\n## Key Design Decisions\n\nSeveral decisions were made to keep the code Aeneas-friendly:\n\n- **`Vec\u003cu8\u003e` instead of `String`** — Aeneas maps `Vec\u003cu8\u003e` directly to Lean's `List U8`\n- **Explicit `while` loops instead of iterators** — translates cleanly to recursive functions\n- **Enum-dispatch instead of `dyn Trait`** — enables simpler case-splitting in proofs\n- **Functional data structures** (e.g., linked-list Stack) — natural inductive types in Lean\n- **`u32` IDs instead of strings** in the verified core — avoids string complexity\n\nSee [PLAN.md](PLAN.md) for the full rationale behind each decision.\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE) for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fe6qu%2Frust-lean-aeneas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fe6qu%2Frust-lean-aeneas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fe6qu%2Frust-lean-aeneas/lists"}