verifying-crypto-with-lean/chapters/appendix-repo-tour.tex

\chapter{A Guided Tour of the Real Repositories}
\label{app:tour}

The companion projects are working code, laid out for auditors rather
than tourists. This appendix is the tourist map, and it ends with three
things done, not read: you will run the full verification yourself,
\emph{sabotage a proof on purpose} and watch the machinery catch you,
and finish at a stop that is not on your disk at all. Everything below
names \code{dalek-ed25519-verified}; the other three ed25519 forks are
structured identically, and \code{pasta-pallas-verified} differs only
where Montgomery form demands it.

\section{The floor plan}

\begin{center}
\small
\begin{tabular}{@{}lp{0.62\linewidth}@{}}
\toprule
\textbf{Path} & \textbf{What it is, and the rule that governs it} \\
\midrule
\code{README.md} & the claims: what is proven, what is frontier ---
the honest-boundary statements of Chapter~\ref{ch:honesty} \\
\code{TRUSTED-BASE.md} & the ledger: every assumption, each with its
reason --- read this \emph{before} being impressed by anything \\
\code{verification/extract.sh} & the extraction recipe (Charon $\to$
LLBC $\to$ Aeneas): ONE merged universe per repo --- field, curve,
scalar, and the verify path --- plus the signature glue \\
\code{verification/gen/} & the extracted model. \textbf{Never
hand-edited} (Chapter~\ref{ch:rust}); regenerated or left alone \\
\code{verification/Proofs/} & the human-written theorems ---
denotations, bounds lemmas, layer certificates. \textbf{No \lean{axiom}
may appear here} (the check script enforces it) \\
\code{verification/check.sh} & THE button: recompiles every shipped
file in dependency order and axiom-audits every certificate; if a file
is in the repo, this script checks it \\
\code{verification/lean-guard} & the resource-capped \lean{lean}
wrapper every compile routes through --- the postmortem-hardened
tooling mentioned in Chapters~\ref{ch:automation}
and~\ref{ch:field} \\
\bottomrule
\end{tabular}
\end{center}

\section{A reading order that works}

\begin{enumerate}[leftmargin=1.6em]
\item \textbf{\code{TRUSTED-BASE.md}} (five minutes). Count the
entries; for each, ask the Chapter~\ref{ch:honesty} question ---
``declared debt or smuggled axiom?'' --- and notice each has its
justification attached.
\item \textbf{The denotation} (in \code{Proofs/}, near the top of the
field spec file). One definition; confirm it is
Chapter~\ref{ch:denotation}'s radix-51 sum, mapping the \emph{extracted}
type.
\item \textbf{One two-clause spec end to end} --- \code{sub} is the
best first read: bounds hypotheses, \lean{.ok} clause, bounds
propagation, value equation, and inside the proof, the $16p$ constant
you audited in Chapter~\ref{ch:field}'s worked example.
\item \textbf{The certificate} --- the conjunction theorem
(\code{fieldImplementation}) and its \lean{\#print axioms} line. This
is the artifact all the marketing language ultimately refers to; note
how unglamorous it looks.
\item \textbf{The apex} --- \code{verify\_accepts\_iff\_decompress}
in \code{Proofs/DecompressMain.lean}, the top of the four-tier stack,
and the check script's boundary phase that guards its axiom cone. Note
how short the capstone proof is: every hard fact was certified below it.
This is where Chapter~\ref{ch:pyramid}'s invitation points.
\end{enumerate}

\section{Running the machinery}

With the toolchain installed (the repos pin exact versions ---
Chapter~\ref{ch:rust}'s reproducibility discipline):

\begin{lstlisting}
$ ./verification/check.sh
=== Phase 1: stub audit ===
  clean: no trivial stubs, no True targets, no axioms outside gen/
=== Phase 2: compile ===
  [gen] CurveField/Funs ... ok
  [proofs] FieldSpec ... ok        (no 'sorry' warnings -- enforced)
=== Phase 3: axiom audit ===
  fieldImplementation: [propext, Classical.choice, Quot.sound]  OK
ALL CHECKS PASSED
\end{lstlisting}

Three details make this script worth imitating in your own projects.
\emph{Phase 1 runs before compilation}: trivial-stub patterns
(\lean{by trivial} specs, \lean{True} targets) and \lean{axiom}
declarations under \code{Proofs/} are cheap textual gates --- the
mechanical half of the Chapter~\ref{ch:honesty} field guide, automated.
\emph{Phase 2 treats warnings as failures}: the string
\lean{uses 'sorry'} in compiler output fails the build --- warnings,
unlike source text, cannot be hidden in comments. \emph{Phase 3 is the
one-command audit}, run on every certificate, every time, so the
axiom-clean property is continuously enforced rather than occasionally
asserted. A fourth phase arrived with the signature layer: \emph{3b pins
the apex tiers' cones to the documented hash/wire-format boundary
EXACTLY} --- an unexpected addition \emph{or removal} fails the build.

\begin{tryit}
Now sabotage it. A green button proves nothing until you have seen it
red for the right reason. In your local clone (nothing here leaves your
machine, and \code{git} undoes it all): pick one digit of one constant
in a \code{Proofs/} statement --- say, turn a $19$ into an $18$ in a
bounds lemma --- and run \code{./verification/check.sh}. Watch which
phase catches it and what the failure actually says. Then try to be
sneakier: weaken a theorem's \emph{statement} instead of its proof, or
plant an \lean{axiom} in a \code{Proofs/} file, and see the stub-audit
phase refuse before the compiler even starts. Restore with
\code{git checkout \ddash\ .} when done. Ten minutes of vandalism buys you
something reading cannot: the difference between believing the button
because it is green and believing it because you have personally failed
to fool it.
\end{tryit}

\section{The control repository}

\code{formal-verification-control} is the method distilled --- written
for the next person (or the next automated agent) to extend the
pyramid without relearning its lessons:

\begin{itemize}[leftmargin=1.4em]
\item \code{INVARIANTS.md} --- the non-negotiables (honesty, safety,
rigor); the source of house rules this book has been quoting.
\item \code{TERRAIN.md} --- the map: pipeline, toolchain, layer status,
representation costs.
\item \code{METHOD.md} --- ways of thinking that worked, stated as
practices rather than commandments.
\item \code{FAILURES.md} --- mapped dead ends \emph{with their tells}:
the memory-exhausting tactic patterns, the extraction scopes that drag
in the world, the kernel-capacity wall. Chapter~\ref{ch:field} told two
of these stories; the file has the rest, and reading failure maps
before starting work is the cheapest experience money can't buy.
\end{itemize}

\section{The last stop is not on your disk}

The repository you just toured does not only sit on your machine or on a
code-hosting site; it is \emph{attested}. The public transparency log at
\code{ltl.zkdefi.org} carries a leaf binding this repo's pinned commit to
the certificate names, their statement fingerprints, and their observed
axiom cones --- the very things your sabotage exercise just tried to
fake locally, notarized globally. Find the leaf for
\code{dalek-ed25519-verified}, and check that the commit it names is the
one you have been reading. Chapter~\ref{ch:attestation} is the full
protocol --- including the fifteen-minute exercise where a stranger (you)
re-derives the log's Merkle root from nothing but published bytes. The
tour ends here on purpose: floor plan, button, sabotage, control room,
and finally the public record that makes the whole thing checkable by
someone who has never met you.

A closing observation to carry out of the tour: nothing in these
repositories asks to be trusted. The claims are in the READMEs, the
assumptions in the ledgers, the checks in a script anyone can run, the
axioms in a one-command audit, the whole ensemble in a public log. That
shape --- \emph{auditability as the default posture} --- is the real
deliverable of the whole verification enterprise, and the standard this
book hopes you now hold everything else to.