Engineering

  • Zig
  • Lean
  • Formal verification

Introducing Zean: Write Zig and prove it in Lean

Write supported Zig functions, translate them into executable Lean models, and prove their memory contracts and algorithm-specific properties with Zean.

Published byOKcontract Labs4 min read

GitHub

Today we’re introducing Zean = Zig + Lean, an open-source toolkit for translating supported Zig functions into executable Lean models and proving their behavior.

With it, you can code your implementation in Zig, then use Lean to make its memory contracts explicit and check them mathematically. Or other properties more specific to your software.

We want to explore a different workflow for systems programming:

  • Keep design iteration in Zig.
  • Once a component settles, state what its callers must provide, prove what the component guarantees, and check those proofs again as the implementation evolves.

For developers considering Rust primarily for memory safety, this offers another direction to investigate: Zig’s explicit control over memory, combined with proofs about selected components.

On November 9, Microsoft’s FORGE Lab described memory-safety bugs in Rust’s standard library, including cases where entirely safe Rust could trigger undefined behavior. The report concerns mistakes in unsafe implementations beneath safe APIs, including assumptions about panics, caller-provided behavior, and operating-system state.

Rust’s ownership system provides broad protections during ordinary development. Its safe abstractions also depend on unsafe implementations honoring their contracts. Rust’s own documentation describes this boundary and the programmer’s responsibility for maintaining it.

Zean provides these contracts through explicit specifications and proofs. That involves more work per verified component, but it also lets us express properties specific to the algorithm: which memory may change, which contents must remain intact, and what a successful result means. At a time where developers use agentic assistance, these larger proofs are tractable!

Consider the copy loop included in the release:

inline fn copyWord(destination: *u32, source: *const u32) void {
    destination.* = source.*;
}

pub export fn copy(destination: [*]u32, source: [*]const u32, length: usize) void {
    var index: usize = 0;
    while (index < length) : (index += 1) {
        copyWord(&destination[index], &source[index]);
    }
}

Its pointers leave important obligations with the caller. The source must contain enough initialized words. The destination must provide enough writable storage. For this copy’s source-preservation contract, the ranges must be disjoint.

In Lean, those requirements become explicit assumptions. The example proves that, under those assumptions, the translated model:

  • Avoids invalid accesses and uninitialized reads throughout execution.
  • Copies the source contents into the destination on successful completion.
  • Preserves the source and caller memory outside the destination.

Modeled allocation exhaustion remains an explicit permitted failure. Termination would be a separate property.

These statements cover every input satisfying the contract. They go beyond checking a collection of example buffers and the caller still has to establish the preconditions.

The copy tutorial includes the implementation, generated model, contracts, proofs, and deliberately false claims that must fail verification.

Zean works from Zig’s analyzed intermediate representation, AIR. An instrumented compiler captures supported functions, and the translator emits executable Lean program definitions. Specifications and proofs live in separate handwritten modules.

The verification library derives obligations for memory access, initialization, permissions, arithmetic, control flow, and supported calls. Developers supply contracts, loop invariants, and any remaining mathematical arguments. Lean checks the resulting proofs. Unsupported operations reject and unresolved proof obligations remain obligations.

We believe this separation is central to the development experience we want. You can explore an implementation before investing in its complete proof. When the design stabilizes, verification can expose assumptions that tests and code review missed and sometimes send you back to improve the implementation.

After a source change, you recapture the function, regenerate its model, and replay the proofs. Changing a loop condition from < length to <= length, for example, introduces an extra boundary access. The original contract cannot justify that access in general.

The intended benefit is more freedom during design, followed by more verification about the component you intend to rely on (compared to Rust for instance). Faster and better development are both goals even if writing and maintaining proofs remains real engineering work.

This first release includes memory-safety examples derived from Ziglings, buffer updates, copy loops, helper calls, and a captured specialization of Zig’s std.mem.replaceScalar. It supports restricted AIR fragments, with explicit target and layout constraints. It's not yet complete!

It's important to note that Lean checks the translated model under its stated assumptions: The capture pipeline, Zig frontend, and native backend remain trust boundaries. That means these proofs do not establish correctness of the final native binary or the whole compiler. Read more in the architecture guide.

To try the included Ziglings demonstration, install Zig 0.17.1 and elan, then run:

git clone https://github.com/okcontract/zean.git
cd zean
elan toolchain install leanprover/lean4:v4.35.0
zig build ziglings

Zean is released under Apache 2.0 at GitHub. If you have a small Zig application whose safety currently depends on a comment you would like to turn into a proof, we’d like to see it.