Skip to content

Prove RISC-V instructions match Clean model: shifts, comparisons and branch conditions. - #1033

Open
nicole-graus wants to merge 41 commits into
mainfrom
formal/riscv-sail
Open

nicole-graus wants to merge 41 commits into
mainfrom
formal/riscv-sail

Conversation

@nicole-graus

@nicole-graus nicole-graus commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Description

Proves, instruction by instruction, that the Clean model in formal/ computes what the official RISC-V spec says.

PR Size: 175 of the 217 files (~176k of ~177.8k lines) are the generated Sail model in sail-riscv-lean/LeanRV64D/; GitHub collapses them (.gitattributes) and CI checks they match their pinned sources. The hand-written part is ~1.8k lines, mostly formal-riscv/.

What's in it

  • formal-riscv/: one chain of three proofs per instruction:
    1. Sail.lean: Sail's execute_* is a pure function (*Pure).
    2. Bridge.lean: *Pure, read as a natural, is the Clean model's function (shiftResult, ltBit, eqBit).
    3. Alu.lean: an ALU bus message with the instruction's flags carries that result, using Alu.Guarantees.
  • Covered: SLL/SRL/SRA (+ immediate and word versions), SLT/SLTU (+ immediate), and the conditions of BEQ/BNE/BLT/BGE/BLTU/BGEU. 22 *_alu_matches_sail theorems, no sorry.
  • sail-riscv-lean/: the Sail RISC-V model in Lean, generated from pinned commits of riscv/sail-riscv and rems-project/sail (PINS, scripts/generate.sh). It replaces opencompl/sail-riscv-lean, which is no longer updated. The Sail compiler is pinned to fix(lean): split variants exceeding runtime constructor limits rems-project/sail#1823 (not merged yet), which splits the instruction type so it compiles on Lean v4.35.0; PINS will move to Sail's main once it is merged.
  • .github/workflows/sail-riscv-lean.yml: regenerates the model and fails if it differs from the committed one.

Not covered yet

  • PC and register file: needs the CPU in Clean. The theorems assume the CPU sends the right operands (ha, hb).
  • Word shifts: only the low 32 bits; the sign extension is done by CPU32.
  • Branches: only the condition, not the jump target.

Notes

ColoCarletti and others added 30 commits October 22, 2026 11:17
…fs and a differential check against the prover
…el to its channel API.

Clean removed StaticLookupChannel in favour of Air.Flat.Lookup, so the structure moves to
LambdaVM/StaticLookup.lean and BITWISE reads its tables through toChannel. Interactions now carry a
direction and a nonnegative multiplicity, and a pull must have multiplicity 0 or 1: EQ, LT and SHIFT
discharge that from their existing bit constraints, and their guarantees are stated for
multiplicity 1 instead of -1. EqLookup is rewritten for the current SoundEnsemble API (a balance
parameter, channels added before tables, unique table names, a demand generation mode per
component), and eq_rows_correct takes the InteractionsFit premise that TableSoundness now has.
Channels/Counted.lean is ported to directions; not_consistent needs only two interactions, since a
pull of multiplicity N >= 2 counts as a push. A grind call in IsByte that no longer closes its goal
is replaced by a direct proof. The export now records each interaction's direction, so the JSON
files are regenerated and lean_diff.rs signs Lean multiplicities by direction. Nothing that is
proven changes.
…p fallback the linter flags.

if_true, if_false, if_pos, if_neg, dif_pos and dif_neg become ite_true, ite_false, ite_eq_left,
ite_eq_right, dite_eq_left and dite_eq_right, as in Clean. In SHIFT, first | ... | skip becomes
try first | ..., which behaves the same. The build has no warnings left.
… the bump, and the renames

left in SHIFT's completeness proof. Both lemmas discharged a pull requirement stated with the old
multiplicity -1 (`¬ -e = -1 → ¬ e = 0 → P`), which the directed interactions no longer produce.
In SHIFT, the hypotheses that needed neg_inj.mp to go from `-x = -1` to `x = 1` now arrive as
`x = 1`, so they are introduced under their final names instead of being copied.
…tates the sign the

comparison uses: a sender (Clean's pull) counts −m and a receiver (Clean's push) +m. The old
first sentence described the prover's LogUp sum, where a sender adds +m, and read as if it
contradicted the code below it. Comment only, no code change.
Clean's Demand.direction is the net sign of a message, pushes minus
pulls, so a demand of direction .pull is one that was pulled more often
than pushed and needs a component that pushes to answer it. EQ pushes
its result on the ALU bus, so its generation mode has to trigger on
.pull, the same way pushStaticComponent does and the same way Clean's
own add8Component and lookup provider do. The field is inert today,
since generation is not part of TableSoundness and nothing here runs
Clean's witness generator, but .push described a component that answers
pushes by pulling, which EQ never does.
The Clean bump changed the things this file documents: pulls carry a
nonnegative multiplicity with an explicit direction instead of a
negative one, a pull owes a multiplicity of 0 or 1, BalancedInteractions
no longer carries the interaction count bound (it moved to the Balance's
fits, reaching soundness as the InteractionsFit premise), and
not_consistent is now a two-interaction witness instead of the p/N
construction. Also lists LambdaVM/StaticLookup.lean, which the bump
added, and records that the export format carries the direction.
Bump Clean to current main (f3abad7c) and Lean to v4.35.0 in formal/
…ed elan, export fails on a missing table entry
…n in README, slimmer lake cache, review fixes
@nicole-graus

Copy link
Copy Markdown
Collaborator Author

/ai-review

@github-actions

Copy link
Copy Markdown

Codex Code Review

No actionable issues found in the PR changes during static review. No builds or tests were run, as requested.

@github-actions

Copy link
Copy Markdown

AI Review

PR #1033 · 216 changed files

Warning: the diff was truncated before review.

Findings

No non-rejected structured findings were reported.

Reviewer Lanes

Lane Model Prompt Status Findings

Native Codex and Claude reviews run separately and post their own comments. They are not included in this structured provenance report.

Raw lane outputs, candidates, final issues, and model metrics are uploaded as workflow artifacts.

@nicole-graus
nicole-graus marked this pull request as ready for review November 17, 2026 14:25
Base automatically changed from formal/clean-model to main November 20, 2026 18:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants