Skip to main content
A spec says what to compute, never how: no memory layout, no tiling, no parallelism, no numerical tricks. Specs are written in Lean 4 over Mathlib’s real numbers ℝ.

Op Specs

An Op Spec is the definition of one operator, with parameters. Here is RMSNorm in two variants, from specs/TheFormalEra/Ops/Norm.lean:
Attention is defined as softmax over the visible positions only, with grouped-query heads:
Subtracting the running max, online softmax and split-KV reduction are implementation choices. The spec does not mention them; a kernel that uses them must be proved equal to this definition. The library’s theorems include softmax_shift (subtracting any reference value leaves softmax unchanged) and flashAttn_eq (online softmax with block skipping equals the attention head). The full list of operators is on Op Specs.

Model Specs

A Model Spec fixes every configuration constant of one checkpoint and assembles Op Specs into a compute graph. The constants are transcribed from the checkpoint’s published config.json; for example, Qwen3.8-27B in specs/TheFormalEra/Spec/Registry.lean:
Each named sub-computation of a layer is a node: input_norm, attn.qkv_proj, attn.core, mlp.act, and so on. A node references an Op Spec and supplies its parameters (H = 5120, eps = 1e-6). The graph also records the value flow: which node’s output feeds which node’s input in every layer.
With --lean, the command also prints the Op Spec’s Lean definition:

Shape and value domains

Disposable inference systems are built for one model, so its dimensions are constants. Only runtime dimensions are symbolic. Each Model Spec has a default shape domain: and a value domain used only for the overflow check: inputs are bf16 activations with |x| ≤ 65504, and weights with |w| ≤ 64. A proof holds for every point in the domain. An annotation may narrow the domain (domain={"T": (1, 8192)}), never widen it: widening is an error.

Why Lean 4

  • The spec, the lifted kernel semantics and the equivalence proof live in one system. The theorem says “kernel semantics = spec” with no translation step in between.
  • The Lean 4 kernel checks every proof, so a closed-source engine does not reduce what you can trust.
  • Mathlib supplies the real numbers, sums, matrices and Real.exp, with a large library of proved facts.
  • You never need to write Lean. theformalera spec show and the Spec Hub site render the formulas.

The oracle

The spec library also builds an executable, theformalera-spec, that evaluates any Model Spec on concrete weights and tokens. Its evaluators are proved equal to the spec (runTrace_fst, and the @[csimp] theorems linear_eq_linearPar, seqMap_eq_seqMapPar). This is what model conformance compares PyTorch implementations against.