veralang 0.1.5__tar.gz

veralang-0.1.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alasdair Allan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

veralang-0.1.5/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: veralang
+Version: 0.1.5
+Summary: Vera: a programming language designed for LLMs, with full contracts, algebraic effects, and typed slot references
+Author-email: Alasdair Allan <alasdair@babilim.co.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://veralang.dev
+Project-URL: Documentation, https://veralang.dev
+Project-URL: Repository, https://github.com/aallan/vera
+Project-URL: Issues, https://github.com/aallan/vera/issues
+Project-URL: Changelog, https://github.com/aallan/vera/blob/main/CHANGELOG.md
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Compilers
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lark>=1.3.1
+Requires-Dist: z3-solver>=4.15.5
+Requires-Dist: wasmtime>=46.0.1
+Provides-Extra: lsp
+Requires-Dist: pygls>=2.0; extra == "lsp"
+Requires-Dist: lsprotocol>=2023.0; extra == "lsp"
+Provides-Extra: dev
+Requires-Dist: pytest>=9.1.1; extra == "dev"
+Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.6; extra == "dev"
+Requires-Dist: mypy>=2.3.0; extra == "dev"
+Requires-Dist: ruff>=0.15.21; extra == "dev"
+Requires-Dist: pre-commit>=4.6.0; extra == "dev"
+Requires-Dist: pip-licenses>=5.5.5; extra == "dev"
+Requires-Dist: veralang[lsp]; extra == "dev"
+Provides-Extra: mutation
+Requires-Dist: veralang[dev]; extra == "mutation"
+Requires-Dist: mutmut>=3.6; extra == "mutation"
+Requires-Dist: pytest-timeout>=2.4; extra == "mutation"
+Requires-Dist: matplotlib>=3.7; extra == "mutation"
+Dynamic: license-file
+
+# Vera
+
+Vera is a programming language designed for large language models to write. It
+has mandatory contracts, algebraic effects, typed slot references instead of
+variable names, and a compiler that emits WebAssembly.
+
+Full documentation, examples, and the language specification are available at
+[veralang.dev](https://veralang.dev) and in the
+[GitHub repository](https://github.com/aallan/vera).
+
+## Install a released version
+
+Vera requires Python 3.11 or later. Create a virtual environment and install
+the `veralang` distribution:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install veralang
+```
+
+On Windows, activate the environment with `.venv\Scripts\activate` instead.
+For editor and agent integration through the language server, install the LSP
+extra:
+
+```bash
+python -m pip install "veralang[lsp]"
+```
+
+The distribution is named `veralang`, but the installed command remains
+`vera`, and Python code still imports it as `import vera`. **Do not run `pip install vera`**: that name belongs to an unrelated
+ERAV citizen-science project on PyPI. The wheel ships the compiler and the
+`vera` command only — the bundled examples, the conformance suite, and the
+specification live in the GitHub repository.
+
+## Install from GitHub source
+
+The source route provides the full environment — the examples, conformance
+programs, and specification alongside the toolchain (the recommended setup for
+agents learning the language) — and remains the route for compiler
+development, unreleased changes, and testing the current `main` branch:
+
+```bash
+git clone https://github.com/aallan/vera.git
+cd vera
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+```
+
+Use `python -m pip install -e ".[lsp]"` for the language server or
+`python -m pip install -e ".[dev]"` when working on the compiler.
+
+## Try it
+
+```vera
+public fn safe_divide(@Int, @Int -> @Int)
+  requires(@Int.1 != 0)
+  ensures(@Int.result == @Int.0 / @Int.1)
+  effects(pure)
+{
+  @Int.0 / @Int.1
+}
+
+public fn main(-> @Int)
+  requires(true)
+  ensures(@Int.result == 5)
+  effects(pure)
+{
+  safe_divide(2, 10)
+}
+```
+
+```bash
+vera check program.vera
+vera verify program.vera    # proves main returns 5 from safe_divide's contract
+vera run program.vera       # prints 5
+```
+
+See the [CLI cookbook](https://github.com/aallan/vera/blob/main/TOOLCHAIN.md),
+[language reference](https://veralang.dev/SKILL.md),
+[supported-platform policy](https://github.com/aallan/vera#supported-platforms),
+and [issue tracker](https://github.com/aallan/vera/issues) for more.

veralang-0.1.5/PYPI_README.md

@@ -0,0 +1,83 @@
+# Vera
+
+Vera is a programming language designed for large language models to write. It
+has mandatory contracts, algebraic effects, typed slot references instead of
+variable names, and a compiler that emits WebAssembly.
+
+Full documentation, examples, and the language specification are available at
+[veralang.dev](https://veralang.dev) and in the
+[GitHub repository](https://github.com/aallan/vera).
+
+## Install a released version
+
+Vera requires Python 3.11 or later. Create a virtual environment and install
+the `veralang` distribution:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install veralang
+```
+
+On Windows, activate the environment with `.venv\Scripts\activate` instead.
+For editor and agent integration through the language server, install the LSP
+extra:
+
+```bash
+python -m pip install "veralang[lsp]"
+```
+
+The distribution is named `veralang`, but the installed command remains
+`vera`, and Python code still imports it as `import vera`. **Do not run `pip install vera`**: that name belongs to an unrelated
+ERAV citizen-science project on PyPI. The wheel ships the compiler and the
+`vera` command only — the bundled examples, the conformance suite, and the
+specification live in the GitHub repository.
+
+## Install from GitHub source
+
+The source route provides the full environment — the examples, conformance
+programs, and specification alongside the toolchain (the recommended setup for
+agents learning the language) — and remains the route for compiler
+development, unreleased changes, and testing the current `main` branch:
+
+```bash
+git clone https://github.com/aallan/vera.git
+cd vera
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+```
+
+Use `python -m pip install -e ".[lsp]"` for the language server or
+`python -m pip install -e ".[dev]"` when working on the compiler.
+
+## Try it
+
+```vera
+public fn safe_divide(@Int, @Int -> @Int)
+  requires(@Int.1 != 0)
+  ensures(@Int.result == @Int.0 / @Int.1)
+  effects(pure)
+{
+  @Int.0 / @Int.1
+}
+
+public fn main(-> @Int)
+  requires(true)
+  ensures(@Int.result == 5)
+  effects(pure)
+{
+  safe_divide(2, 10)
+}
+```
+
+```bash
+vera check program.vera
+vera verify program.vera    # proves main returns 5 from safe_divide's contract
+vera run program.vera       # prints 5
+```
+
+See the [CLI cookbook](https://github.com/aallan/vera/blob/main/TOOLCHAIN.md),
+[language reference](https://veralang.dev/SKILL.md),
+[supported-platform policy](https://github.com/aallan/vera#supported-platforms),
+and [issue tracker](https://github.com/aallan/vera/issues) for more.

veralang-0.1.5/README.md

@@ -0,0 +1,347 @@
+# Vera
+
+[![Vera — A language designed for machines to write](assets/vera-social-preview.jpg)](https://veralang.dev)
+
+[![CI](https://github.com/aallan/vera/actions/workflows/ci.yml/badge.svg)](https://github.com/aallan/vera/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/aallan/vera/graph/badge.svg)](https://codecov.io/gh/aallan/vera)
+[![Mutation score](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/aallan/vera/main/mutation.json)](https://github.com/aallan/vera/issues/387)
+
+**Vera** (v-ERR-a) is a programming language designed for large language models to write. The name comes from the Latin *veritas* (truth). Programs compile to WebAssembly and run at the command line, in the browser, or — experimentally — on stock WASI Preview 2 hosts.
+
+```vera
+public fn safe_divide(@Int, @Int -> @Int)
+  requires(@Int.1 != 0)
+  ensures(@Int.result == @Int.0 / @Int.1)
+  effects(pure)
+{
+  @Int.0 / @Int.1
+}
+```
+
+There are no variable names. `@Int.0` is the most recent `Int` binding; `@Int.1` is the one before. The `requires` clause is a precondition the compiler checks at every call site. The `ensures` clause is a postcondition the SMT solver proves statically. The function is `pure` — no side effects of any kind. If any of this is wrong, the code does not compile.
+
+## Why?
+
+Programming languages have always co-evolved with their users. Assembly emerged from hardware constraints. C from operating systems. Python from productivity needs. If models become the primary authors of code, it follows that languages should adapt to that too.
+
+The evidence suggests the biggest problem models face isn't syntax, instead it's coherence over scale. Models struggle with maintaining invariants across a codebase, understanding the ripple effects of changes, and reasoning about state over time. They're pattern matchers optimising for local plausibility, not architects holding the entire system in mind. The [empirical literature](https://arxiv.org/abs/2307.12488) shows that models are particularly vulnerable to naming-related errors like choosing misleading names, reusing names incorrectly, and losing track of which name refers to which value.
+
+Vera addresses this by making everything explicit and verifiable. The model doesn't need to be right, it needs to be checkable. Names are replaced by structural references. Contracts are mandatory. Effects are typed. Every function is a specification that the compiler can verify against its implementation.
+
+See the **[FAQ](FAQ.md)** for deeper questions about the design — why no variable names, what gets verified, how Vera compares to Dafny/Lean/Koka/F*, and the empirical evidence behind the design choices.
+
+## What Vera looks like
+
+Three examples that show what makes Vera different. For the full tour — contracts, refinement types, ADTs, effects, exception handling, recursion, Markdown, JSON, HTML, HTTP, LLM inference — see **[EXAMPLES.md](EXAMPLES.md)**.
+
+### Contracts the compiler proves
+
+A precondition like `requires(@Int.1 != 0)` becomes a static obligation: the SMT solver proves it holds at every call site, or refuses to compile.  A program that calls `safe_divide` with a divisor the verifier can't prove non-zero is a compile error, not a runtime error.
+
+```vera
+public fn safe_divide(@Int, @Int -> @Int)
+  requires(@Int.1 != 0)
+  ensures(@Int.result == @Int.0 / @Int.1)
+  effects(pure)
+{
+  @Int.0 / @Int.1
+}
+```
+
+The compiler synthesises the same obligations for primitive operations themselves.  Computing `@Int.1 / @Int.0` where the verifier finds the divisor can be zero is now a compile error (E526), not a runtime trap (an opaque or untranslatable divisor it can neither prove non-zero nor witness a zero for stays Tier 3, guarded at runtime by the zero-divisor trap); an array index is proved in bounds where the length is statically known, a compile error (E527) where provably out of bounds, and otherwise bounds-checked at runtime; `@Nat` subtraction underflow and `@Int` → `@Nat` narrowing are checked the same way.  So a division or array index that `vera verify` reports as proven is safe for all inputs; where it can't prove one — an opaque divisor, a dynamic array length, or an op inside a closure body — the runtime guard catches it rather than silently producing a wrong value.  (Float division is exempt: divide-by-zero yields inf/NaN, not a trap.)
+
+### Effects are explicit
+
+Vera is pure by default. A function that calls an LLM says so in its signature. A caller that doesn't permit `<Inference>` cannot invoke it. A caller that doesn't permit `<Http>` cannot invoke it either. Both callers must declare the full effect row.
+
+```vera
+public fn research_topic(@String -> @Result<String, String>)
+  requires(string_length(@String.0) > 0)
+  ensures(true)
+  effects(<Http, Inference>)
+{
+  let @Result<String, String> = Http.get(
+    string_concat("https://search.example.com/?q=", @String.0));
+  match @Result<String, String>.0 {
+    Ok(@String) -> Inference.complete(
+      string_concat("Summarise this research:\n\n", @String.0)),
+    Err(@String) -> Err(@String.0)
+  }
+}
+```
+
+Six lines of logic. The signature carries all the ceremony — parameter types, contracts, effect declarations — so the body reads like a pipeline. Run a real example with `VERA_ANTHROPIC_API_KEY=sk-ant-... vera run` [`examples/inference.vera`](examples/inference.vera).  See [`ENVIRONMENT.md`](ENVIRONMENT.md) for all `VERA_*` environment variables (provider keys, runtime knobs, debug flags).
+
+### Errors are instructions
+
+Traditional compilers produce diagnostics for humans: `expected token '{'`. Vera produces instructions for the model that wrote the code. Every error includes what went wrong, why, how to fix it with a concrete code example, and a spec reference.
+
+```
+[E001] Error at main.vera, line 14, column 1:
+
+    {
+    ^
+
+  Function is missing its contract block. Every function in Vera must declare
+  requires(), ensures(), and effects() clauses between the signature and the body.
+
+  Vera requires all functions to have explicit contracts so that every function's
+  behaviour is mechanically checkable.
+
+  Fix:
+
+    Add a contract block after the signature:
+
+      private fn example(@Int -> @Int)
+        requires(true)
+        ensures(@Int.result >= 0)
+        effects(pure)
+      {
+        ...
+      }
+
+  See: Chapter 5, Section 5.2 "Function Declaration Syntax"
+```
+
+Every diagnostic has a stable error code (`E001`–`E702`) and is available as structured JSON via the `--json` flag.
+
+## Getting started
+
+### Prerequisites
+
+- Python 3.11+
+- Git
+- Node.js 22+ *(optional, for browser runtime and parity tests)*
+
+### Installation
+
+Install the released `veralang` distribution from PyPI:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+python -m pip install veralang
+```
+
+The distribution is named `veralang`, but the installed command remains
+`vera`, and Python code still imports it as `import vera`. For editor and agent integration through the language server, install
+`python -m pip install "veralang[lsp]"`. Do not run `pip install vera`: that
+name belongs to an unrelated project on PyPI. The wheel ships the compiler and
+the `vera` command only — the bundled `examples/`, the conformance suite, and
+the specification live in the repository, not in the wheel.
+
+The GitHub source route is the recommended environment for agents and for
+anyone learning the language — it provides the examples, conformance programs,
+and spec that [SKILL.md](SKILL.md) teaches from, alongside the toolchain — and
+it remains the route for compiler development, unreleased changes, and testing
+the current `main` branch:
+
+```bash
+git clone https://github.com/aallan/vera.git
+cd vera
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+python -m pip install -e ".[dev]"
+```
+
+`[dev]` includes everything (tests, linters, the language server). For a lighter
+source install that only adds editor/agent support to the base toolchain, use
+`python -m pip install -e ".[lsp]"` — see [LSP_SERVER.md](LSP_SERVER.md).
+
+#### Supported platforms
+
+Tested in CI on every commit:
+
+- **macOS 15 (Sequoia) and macOS 26 (Tahoe)** on Apple Silicon, against Python 3.11, 3.12, 3.13
+- **Ubuntu 24.04 LTS** on x86_64, against Python 3.11, 3.12, 3.13
+- **Ubuntu 24.04 LTS** on aarch64, against Python 3.12 (advisory job — runs on every commit, does not gate merges yet)
+- **Windows Server 2022** on x86_64, against Python 3.11, 3.12, 3.13
+
+Untested but expected to work (wheels available for all dependencies):
+
+- Linux x86_64 with glibc 2.27+ (Ubuntu 18.04+ / Debian 10+ / RHEL 8+)
+- Linux aarch64 with glibc 2.38+ on Python 3.11 / 3.13 (the 3.12 cell is CI-tested above; e.g. Ubuntu 23.10+)
+- macOS 15+ on Intel (x86_64)
+
+Out of scope — `pip install -e .` will fail at dependency resolution (clear "no matching distribution" error rather than a cryptic source-build failure):
+
+- **macOS 14 (Sonoma) and earlier** — see [#691](https://github.com/aallan/vera/issues/691) for the documented decision and workarounds
+- **Linux aarch64 with glibc < 2.38** (e.g. Ubuntu 22.04 LTS aarch64) — see [#701](https://github.com/aallan/vera/issues/701)
+
+The macOS 15+ baseline reflects [TelemetryDeck's macOS version distribution data](https://telemetrydeck.com/survey/apple/macOS/versions/): macOS 26 (~75%) and macOS 15 (~24%) account for ~99% of the macOS install base; macOS 14 is ~1.4% and falling. The cost of supporting older macOS versions does not earn its keep at that share.
+
+### The workflow
+
+![The workflow: an LLM agent writes Vera with mandatory contracts; vera check and vera verify prove the types and contracts, feeding every diagnostic — description, rationale, fix, spec_ref — straight back to the agent; when the proofs hold, vera run executes the WebAssembly on CLI, browser, WASI or HTTP.](assets/diagrams/workflow.svg)
+
+```
+$ vera check examples/absolute_value.vera
+OK: examples/absolute_value.vera
+
+$ vera verify examples/safe_divide.vera
+OK: examples/safe_divide.vera
+Verification: 4 verified (Tier 1)
+
+$ vera run examples/hello_world.vera
+Hello, World!
+```
+
+`vera check` parses and type-checks. `vera verify` adds contract verification via Z3 — Tier 1 contracts (decidable arithmetic, comparisons, Boolean logic, ADTs, termination) are proved automatically; contracts Z3 cannot decide become Tier 3 runtime checks. `vera run` compiles to WebAssembly and executes.
+
+```bash
+vera run file.vera --fn f -- 42           # call function f with argument 42
+vera compile --target browser file.vera   # emit browser bundle
+vera compile --target wasi-p2 file.vera   # emit a WASI Preview 2 component (experimental)
+vera run --target wasi-p2 file.vera       # execute under the built-in WASI 0.2 host
+vera serve file.vera                      # serve handle(Request -> Response) over HTTP (default :8000)
+vera compile --target wasi-p2 --world server file.vera  # wasi:http server component for wasmtime serve
+vera test file.vera                       # contract-driven testing via Z3 + WASM
+vera fmt file.vera                        # format to canonical form
+vera verify --json file.vera              # JSON diagnostics for agent feedback loops
+vera check --explain-slots file.vera     # show slot resolution table (which @T.n maps to which param)
+vera lsp                                 # serve the Language Server Protocol over stdio (see LSP_SERVER.md)
+vera version                             # print the installed version
+vera builtins --json                     # list the built-in function registry (no file needed)
+vera effects --json                      # list the effect and ability registry (no file needed)
+vera errors --json                       # list the diagnostic error-code registry E001–E702 (no file needed)
+```
+
+`vera compile --target browser` produces a self-contained bundle (wasm + JS runtime + HTML) that runs in any browser — no build step, no bundler. Mandatory parity tests ensure identical behaviour between the command-line and browser runtimes for the pure-language surface (arithmetic, ADTs, pattern matching, closures, contracts, effects-as-host-imports, etc.).  The IO surface is the documented exception: terminal Vera programs that rely on `IO.sleep` for animation pacing or ANSI escape codes for cursor control compile cleanly to `--target browser` but render the escapes as literal text and freeze the tab while sleeping — the browser target expects Vera to be the pure simulation core and JavaScript to drive timing and rendering ([SKILL.md §Browser compilation](SKILL.md#browser-compilation) has the recommended pattern).
+
+`vera compile --target wasi-p2` emits an **experimental WASI Preview 2 target (IO and Random surface)**: a binary WebAssembly component whose host imports are implemented over WASI 0.2 interfaces, runnable by any stock wasip2 host (`wasmtime run` needs no flags and no Vera bindings). Programs using host families beyond IO/Random are rejected with a diagnostic naming the family — never silently compiled against the core target. See [spec chapter 13](spec/13-wasi.md) for the architecture, the supported surface, and the documented divergences (WASI 0.2's ok/err-only exit codes, no structured trap frames across the component boundary). With `--world server`, the same contract-verified `handle(Request -> Response)` program `vera serve` hosts natively compiles to a `wasi:http/incoming-handler` component that stock `wasmtime serve` runs unmodified — verified HTTP handlers as a portable deployment artifact (`--world server` is only valid together with `--target wasi-p2`; the CLI rejects other combinations).
+
+### Editor support
+
+Vera ships a [language server](LSP_SERVER.md) (`vera lsp`, via the optional `[lsp]` extra) that keeps a warm incremental Z3 session between keystrokes — diagnostics, proofs, hover, slot go-to-definition, and typed-hole completion at editor latency, plus custom proof-delta methods for coding agents. See **[LSP_SERVER.md](LSP_SERVER.md)** for setup and the full protocol surface.
+
+- **[VS Code extension](editors/vscode/)** — starts the language server automatically, plus syntax highlighting and language configuration
+- **[TextMate bundle](editors/textmate/)** — syntax highlighting for Sublime Text and other TextMate-grammar editors (any editor with a generic LSP client can use `vera lsp` directly)
+
+## For agents
+
+Vera ships with these files for LLM agents:
+
+- [`SKILL.md`](SKILL.md) — Complete language reference. Covers syntax, slot references, contracts, effects, common mistakes, and working examples.
+- [`AGENTS.md`](AGENTS.md) — Instructions for any agent system (Copilot, Cursor, Windsurf, custom). Covers both writing Vera code and working on the compiler.
+- [`CLAUDE.md`](CLAUDE.md) — Project orientation for Claude Code. Key commands, layout, workflows, and invariants.
+- [`DE_BRUIJN.md`](DE_BRUIJN.md) — Deep dive into Vera's typed slot references: the academic background, worked examples, the commutative-operations trap, and connections to proof assistants and LLM code-generation research.
+- [`TOOLCHAIN.md`](TOOLCHAIN.md) — The CLI cookbook: driving the toolchain to write, verify, test, run, and debug Vera, plus the `builtins`/`effects`/`errors` introspection commands.
+
+**Claude Code** discovers `SKILL.md` and `CLAUDE.md` automatically in this repo. For other projects, install the skill manually:
+
+```bash
+mkdir -p ~/.claude/skills/vera-language
+cp /path/to/vera/SKILL.md ~/.claude/skills/vera-language/SKILL.md
+```
+
+**Other models** — include `SKILL.md` in the system prompt, as a file attachment, or as a retrieval document. The file is self-contained and works with any model that can read markdown.
+
+**Essential rules** for writing Vera code:
+
+1. Every function needs `requires()`, `ensures()`, and `effects()` between the signature and body
+2. Use `@Type.index` to reference bindings — `@Int.0` is the most recent `Int`, `@Int.1` is the one before
+3. Declare all effects — `effects(pure)` for pure functions, `effects(<IO>)` for IO, etc.
+4. Recursive functions need a `decreases()` clause
+5. Match expressions must be exhaustive
+
+## Project status
+
+Vera is in **active development** at v0.1.5: 2,000+ commits, 203 releases, 7,992 tests, 95% code coverage, 163 conformance programs, 39 examples, and a 14-chapter specification. Known bugs and limitations are tracked in **[KNOWN_ISSUES.md](KNOWN_ISSUES.md)**. See **[HISTORY.md](HISTORY.md)** for how the compiler was built.
+
+The reference compiler — parser, AST, type checker, contract verifier (Z3), WASM code generator, module system, browser runtime, and runtime contract insertion — is working. The language specification is in draft across [14 chapters](spec/).
+
+**Key features delivered:** [typed De Bruijn indices](DE_BRUIJN.md) (`@T.n`), mandatory contracts, algebraic effects (IO, Http, HttpServer, State, Exceptions, Async, Inference, Random, Diverge), refinement types, constrained generics (Eq, Ord, Hash, Show), algebraic data types, pattern matching, modules, 164 built-in functions (strings, arrays, maps, sets, decimals, math, JSON, HTML, Markdown, regex, base64, URL), contract-driven testing, canonical formatter, browser runtime, three-tier verification design (Z3 static and runtime fallback shipped; the Z3-guided tier is specified, not yet implemented), a [language server](LSP_SERVER.md) with warm incremental verification and agent-facing proof-delta methods, and contract-verified HTTP handlers served natively (`vera serve`) or as wasi:http components for stock `wasmtime serve` (`--target wasi-p2 --world server`).
+
+**What's next:** the path from "working language" to "the language agents actually use" — see **[ROADMAP.md](ROADMAP.md)** for the four strategic milestones. The flagship goal is a verified MCP tool server where contracts guarantee tool schemas at compile time. **[VeraBench](https://github.com/aallan/vera-bench)** — a 50-problem benchmark across 5 difficulty tiers — now covers 6 models across 3 providers (v0.0.7). The headline result: Kimi K2.5 achieves 100% run_correct on Vera, beating both Python (86%) and TypeScript (91%). Three models beat TypeScript on Vera; the flagship tier averages 93% Vera vs 93% Python — essentially parity. These are single-run results with high variance — see the [full report](https://github.com/aallan/vera-bench) for details.
+
+Known bugs and open issues are tracked on the **[issue tracker](https://github.com/aallan/vera/issues)**. See **[KNOWN_ISSUES.md](KNOWN_ISSUES.md)** for a consolidated list.
+
+The compiler is a seven-stage pipeline — see [vera/README.md](vera/README.md) for the architecture in depth:
+
+![The compiler pipeline and module map: parse, transform and resolve feed the two-pass type checker; vera verify proves each contract obligation or defers it to a runtime guard, with a warm-verification sidecar for the LSP, while vera compile emits WAT and WASM for the wasmtime host, the browser bundle, or a WASI 0.2 component.](assets/diagrams/architecture.svg)
+
+<details>
+<summary><strong>Project structure</strong></summary>
+
+```
+vera/
+├── SKILL.md                       # Language reference for LLM agents
+├── AGENTS.md                      # Instructions for any AI agent system
+├── CLAUDE.md                      # Project orientation for Claude Code
+├── FAQ.md                         # Design rationale and comparisons
+├── EXAMPLES.md                    # Language tour with code examples
+├── HISTORY.md                     # How the compiler was built
+├── ROADMAP.md                     # Forward-looking language roadmap
+├── KNOWN_ISSUES.md                # Known bugs and limitations
+├── DESIGN.md                      # Technical decisions and prior art
+├── TESTING.md                     # Testing reference (single source of truth)
+├── CONTRIBUTING.md                # Contributor guidelines
+├── CHANGELOG.md                   # Version history
+├── LICENSE                        # MIT licence
+├── spec/                          # Language specification (14 chapters)
+├── vera/                          # Reference compiler (Python)
+│   ├── grammar.lark               #   Lark LALR(1) grammar
+│   ├── parser.py                  #   Parser module
+│   ├── ast.py                     #   Typed AST node definitions
+│   ├── transform.py               #   Lark parse tree → AST transformer
+│   ├── checker/                   #   Type checker (mixin package)
+│   ├── verifier.py                #   Contract verifier (Z3)
+│   ├── codegen/                   #   Code generation (13 modules)
+│   ├── wasm/                      #   WASM translation (19 modules)
+│   ├── browser/                   #   Browser runtime
+│   ├── formatter.py               #   Canonical code formatter
+│   ├── errors.py                  #   LLM-oriented diagnostics
+│   ├── obligations/               #   Reified proof obligations + warm incremental verification
+│   ├── lsp/                       #   Language server (see LSP_SERVER.md)
+│   └── cli.py                     #   Command-line interface
+├── docs/                          # GitHub Pages site (veralang.dev)
+├── editors/                       # VS Code extension (LSP client + grammar) + TextMate bundle
+├── examples/                      # 39 example Vera programs
+├── tests/                         # Test suite (see TESTING.md)
+└── scripts/                       # CI and validation scripts
+```
+
+</details>
+
+For compiler architecture and internals, see [`vera/README.md`](vera/README.md). For testing details, see **[TESTING.md](TESTING.md)**.
+
+## Design
+
+See **[DESIGN.md](DESIGN.md)** for the full technical decisions table (representation, references, contracts, effects, verification, memory, target, grammar, diagnostics, data types, polymorphism, collections, error handling, recursion, naming) and **[prior art](DESIGN.md#prior-art)** (Eiffel, Dafny, F*, Koka, Liquid Haskell, Idris, SPARK/Ada, bruijn, TLA+/Alloy).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to Vera. For compiler internals, see [vera/README.md](vera/README.md).
+
+## Citation
+
+If you use Vera in your research, please cite:
+
+```bibtex
+@software{vera2026,
+  author = {Allan, Alasdair},
+  title = {Vera: a programming language designed for LLMs to write},
+  year = {2026},
+  url = {https://github.com/aallan/vera}
+}
+```
+
+## Licence
+
+Vera is licensed under the [MIT License](LICENSE).
+
+All direct dependencies are MIT or Apache-2.0. One transitive dependency (`chardet`, via `cyclonedx-bom`) is LGPL v2+, which is compatible with MIT redistribution. Licence compliance is enforced by CI.
+
+| Dependency | Licence | Role |
+|-----------|---------|------|
+| [Lark](https://github.com/lark-parser/lark) | MIT | LALR(1) parser generator |
+| [z3-solver](https://github.com/Z3Prover/z3) | MIT | SMT solver for contract verification |
+| [wasmtime](https://github.com/bytecodealliance/wasmtime) | Apache-2.0 | WebAssembly runtime |
+
+Copyright &copy; 2026 Alasdair Allan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.