imprimatur

Imprimatur ("let it be printed") keeps the LaTeX of a paper in step with a Lean 4 development.

  • Generated content. Authors mark places in ordinary .tex files where a Lean declaration should appear: a theorem statement, a definition, a set of inference rules or a grammar. imprimatur renders that content from the compiled Lean environment, in the paper's own notation, and splices it in place.
  • Checked prose. Hand-written theorem prose can be tied to the Lean results it describes. The build then fails if a result disappears, depends on sorry or a disallowed axiom, or changes its statement after an author last checked the prose against it.
  • Faithful notation. Every formula imprimatur typesets is read back, in the grammar of the paper's notation, and must mean the Lean statement it came from: one reading, and the right one.

The .tex files stay ordinary LaTeX, so they compile on Overleaf and arXiv with no preprocessor. The host Lean project doesn't need to change.

Try it in two minutes

You need elan (curl -sSfL https://raw.githubusercontent.com/leanprover/elan/master/elan-init.sh | sh) and, for the PDF, a TeX distribution with latexmk (Debian and Ubuntu: apt install texlive-latex-extra texlive-science latexmk). The commands below build imprimatur, then a short paper on a typed λ-calculus from the Lean development that proves its theorems:

git clone --depth 1 https://github.com/theorem-press/imprimatur.git
cd imprimatur/splice && lake build && export PATH="$PWD/.lake/build/bin:$PATH"
cd ../examples/semantics
(cd host && lake build)
imprimatur build --profile public --commit "$(git rev-parse HEAD)"
imprimatur check
git --no-pager diff paper.tex
latexmk -pdf paper.tex

Line by line: build the splicer and put it on the path; build the Lean development, as its owners would; imprimatur build renders the grammar, rules and theorems into paper.tex, building an extractor for the host's Lean the first time, and under the public profile at the commit you cloned it also links every theorem, example, checked sentence and row of the index of notation to its Lean on GitHub (docs/blocks.md); imprimatur check reports nothing stale, untrusted or unfaithful; the diff is the TeX imprimatur wrote, since the committed paper.tex has empty blocks and the hand-written prose around them is untouched; and latexmk typesets paper.pdf, which open paper.pdf shows on macOS and xdg-open paper.pdf on Linux. The result is the PDF the site builds from these commands. expected/paper.tex is the same paper built for submission, by imprimatur build with no profile, which leaves the links out, and with the hashes on its five \leancheck sentences that imprimatur accept --all records once an author has read each sentence against the Lean result it names (docs/trust.md). Clone to PDF took about a minute on one machine; the first run also downloads Lean v4.35.0.

What it looks like

In Lean, from examples/semantics:

theorem preservation {e e' : Tm} (hs : Step e e') :
    ∀ {Γ : Ctx} {t : Ty}, HasType Γ e t → HasType Γ e' t

In the paper, the author writes an empty block that names the theorem:

\begin{leantheorem}{Stlc.preservation}{Preservation}
\end{leantheorem}

The first argument is the key, the Lean name of the declaration to show; the second is the theorem's title. leantheorem is an environment the paper's imprimatur.toml declares, as a sentence (the prose view) wrapped in theorem:

[aliases]
leantheorem = { view = "prose", wrap = "theorem", label = "thm:{key}" }

imprimatur build looks up Stlc.preservation, renders it with the notation the paper declares for Step, HasType and the rest, and fills in the block:

\begin{leantheorem}[sum=jU5x8J0Hfl]{Stlc.preservation}{Preservation}
\label{thm:Stlc.preservation}
\LeanProse{Let $e, e' \in \mathit{Term}$, $\Gamma \in \mathit{Context}$ and
$\tau \in \mathit{Type}$. Assume $e \longrightarrow e'$ and
$\Gamma \vdash e : \tau$. Then $\Gamma \vdash e' : \tau$.}
\end{leantheorem}

which typesets as a theorem: Let e, e′ ∈ Term, Γ ∈ Context and τ ∈ Type. Assume e ⟶ e′ and Γ ⊢ e : τ. Then Γ ⊢ e′ : τ. The sum= checksum records what was generated. If the Lean theorem changes, imprimatur check reports the block as stale; if someone edits it by hand, as edited; if the theorem comes to depend on sorry, as untrusted.

A key can also be a title the paper uses, mapped to the Lean name in the notation module (latex_entry "Preservation" => Stlc.preservation), as examples/semantics does.

What the block rests on

Between the Lean development and the paper there is one file, the bundle, which imprimatur build writes and the splicer reads. Its entry for the theorem above is, abridged:

"Stlc.preservation": {
  "kind": "theorem",
  "stmtHash": "a89b1dbd…",
  "sigHash":  "dd711a64…",
  "views": { "prose": "\\LeanProse{Let $e, e' \\in \\mathit{Term}$ …}", "math": "…" },
  "sorry": false, "axioms": [], "cone": { "size": 16, "untrusted": [] }
}

It says nothing about the proof of preservation, and cannot: the splicer never sees Lean. It carries two images of the statement, a hash that names its meaning and TeX that shows it, and a verdict on the proof. That is the whole interface, and it is a Lean type, Bundle (Image TeX) Verdict in bundle/Bundle.lean, of which the file is the JSON.

The type comes with its meaning. A bundle is true of a development when every claim it makes holds of the statement it is about: the hash is that statement's, each view is that statement rendered, and a view with no recorded problems reads back as it. A bundle may say less than Lean knows, a view it could not render, a hash it could not compute, never something false; where it is silent, check reports the silence.

That is enough for one theorem, proved in Lean for a model of the splicer (splice/SpliceModel):

If imprimatur check reports nothing, and the bundle is true, then the paper is true: every displayed formula is a statement Lean proved, rendered by the paper's notation, and reads back as that statement; and every \leancheck names, by its hash, a statement Lean proved.

The theorem's hypothesis is the trust boundary, stated once: the extractor is honest about the development, and SHA-256 does not collide. Everything after that, generation, hand edits, staleness, slot text, drift, is covered by the proof.

What it does

  • Views: a declaration as Lean prints it (lean), as a formula (math, or its defining equations with def), as a sentence (prose), as inference rules (rules), as a BNF grammar (grammar), or its source, axioms and sorry status (meta). Indexes of the paper's metavariables, its notation and its results are views too. See docs/views.md.
  • Notation is declared in Lean, with latex_notation, latex_category and latex_style, and shared packs for logic, sets, order and common Mathlib notation. See docs/notation.md.
  • Trust checks: results that disappear, depend on sorry or a disallowed axiom, or whose statement changed since \leancheck recorded it. Comparator manifests and leanblueprint's \lean{…} are read too. With checker = "con-leche", the development must also be accepted by the verified checker the Lean toolchain ships, whose acceptance is proved to give it a model. See docs/trust.md.
  • Translation validation: each formula is parsed back in the notation's grammar, and one that is ambiguous, cannot be read back, or reads as something other than its statement is reported where it is. The parser is proved sound and complete, so a formula that passes has no reading in the grammar but its statement's (docs/verified-validator.md). With latex_style categories := strict, a variable is always written with its type's letter, so a reader can tell its type.
  • Three modes: inside the Lean project, as a sidecar package, or external, which leaves the host project untouched. See docs/blocks.md.

Using it in your own paper

imprimatur reads a built Lean project in one of three modes (docs/blocks.md): external, which reads the project as it is, as the example above does, with the notation in a file beside the paper; sidecar, a Lake package beside the host that requires it; or in-project, where the host's lakefile requires imprimatur. The repository is the extractor's package at its root, so the last two need no subDir:

[[require]]
name = "imprimatur"
git = "https://github.com/theorem-press/imprimatur"
rev = "main"   # pin a commit

A paper is a directory with an imprimatur.toml naming the main .tex file, the Lean project, the modules to import and the notation module. In it:

imprimatur build
imprimatur check
latexmk -pdf paper.tex

build renders and splices the blocks, and check reports what is stale, untrusted or unfaithful.

In external mode the first run builds an extractor for the host's Lean version, once per version, into ~/.cache/imprimatur; imprimatur toolchain install VERSION does it ahead of time, and --no-install fails instead, for CI that must not compile what it did not ask for. An extractor built from other sources than the running imprimatur, by another checkout say, is rebuilt the same way.

examples/ has five working papers: one for each mode, the longer one on a λ-calculus built above, and a note on a Mathlib host that states what the Lean archive claiming the Riemann Hypothesis claims.

Status

Usable now from source: build it from main, as in Getting started above. It works on Lean v4.28.0-rc1 to v4.35.0, and builds the papers of two programming-language projects, whose grammars, rules and results are generated, and a paper about imprimatur itself (in preparation), whose theorems about the splicer, and about the extractor's layouts, are proved in Lean (splice/SpliceModel).

There is no tagged release yet, so pin a commit if you depend on it. The first release, v0.5.0, adds an index of every result a paper cites, check --anonymous for double-blind submission and init, and lists imprimatur on Reservoir: see the v0.5.0 milestone. Other planned work is in the issues.

More

  • DESIGN.md: the architecture (a Lean-side extractor and a text-only splicer, connected by a versioned JSON bundle), the notation language, the trust checks, prior art, and what correctness means (§18).
  • CHANGELOG.md: what has changed.
  • CONTRIBUTING.md and docs/TESTING.md: working on the code.

License

Apache-2.0. See LICENSE.