Skip to content

JIT J.5: clazel-lir syntax, semantics and typing, with soundness proven - #191

Open
atiernan wants to merge 10 commits into
claude/js-syntax-specfrom
claude/lir-spec
Open

atiernan wants to merge 10 commits into
claude/js-syntax-specfrom
claude/lir-spec

Conversation

@atiernan

Copy link
Copy Markdown
Member

JIT plan item J.5: clazel-lir, LIR's syntax, semantics and typing, with the typing's soundness proven. There is no back end or front end yet. The crate stays at tier 0, and its target tier is 2.

This PR is part of stack #188, on top of #190. It shares nothing with that PR beyond the Cargo.lock and PLACES lines.

What's here

  • src/syntax.rs: LIR as jit.md describes it.
    • Control flow: structured, with block, loop, if, br, br_if and br_table.
    • Values: i32, i64 and f64, plus Idx(region, size), an i64 that a bounds_check has checked.
    • Memory: loads and stores, each tagged with its region.
    • Exits: exit(code, operands).
    • Not allowed: calls and indirect branches.
  • src/spec.rs: a big-step semantics with fuel. It ends in Normal, Branch, Exit, Stuck or OutOfFuel.
    • The table of regions (base and bound) is a parameter, and memory is a partial map.
    • A load or store outside its region is Stuck.
    • Integer ops wrap.
    • Each instruction cites the Wasm core 2.0 section it mirrors.
  • src/typing.rs: a type checker, tc. Terminators must end their sequence, so LIR has no stack-polymorphic dead code.
  • src/soundness.rs: tc_sound, and run_sound for a whole function body. A well-typed program on a state that matches its types:
    • never gets stuck, and every load and store names an existing region and stays inside its bound;
    • returns normal results that match the static types;
    • branches only to existing labels, carrying values of the label's types.
  • src/examples.rs:
    • A bounds-checked load types, and is never stuck for any index.
    • The same load is rejected if the check is removed, if a 4-byte check guards an 8-byte load, or if dead code follows br.
    • An out-of-range index exits with the check's code.
    • A countdown loop types and is never stuck.
    • Storing then loading an i32 gives back the stored value.
  • The Wasm coverage check jit.md asks for is in the crate docs (lib.rs), with what a front end would do about each gap.

For the spec reviewer, first

These are listed in the header of src/spec.rs.

  1. Big-step with fuel, rather than Wasm's small-step label reduction. A branch is the outcome Branch(l, st), which the enclosing label catches.
  2. Blocks: a block body runs on a fresh stack that holds only its parameters.
  3. One function body and no calls. return is a branch to label 0, and a Wasm trap or a call to a runtime service is an Exit.
  4. bounds_check and the index mask are LIR's own, not Wasm's. The mask does nothing once the check has passed, so check that jit.md's Spectre mask isn't standing in for a real requirement.
  5. f64: the arithmetic and the conversions (f64_add, f64_sub, f64_mul, f64_div, f64_sqrt and f64_of_int) are uninterpreted spec fns, as in clazel-js-vm. Comparisons, neg and abs are exact on the bits. Check f64_key against Wasm's feq, flt and the other comparisons.
  6. Shift counts are taken mod N.
  7. select is the untyped form, restricted to operands of one type.
  8. Typing:
    • Idx(region, size) is a subtype of i64, and of Idx with a smaller size.
    • br_if and br_table match a label's types against the stack after popping the condition.
    • A loop's label carries the block's parameter types.

Wasm gaps (recorded in the crate docs)

  • Integer: clz, ctz, popcnt, div and rem. The sign-extension ops can be written as shl then shr_s.
  • f64: ceil, floor, trunc, nearest, min, max and copysign.
  • Conversions: trunc and trunc_sat to integer. JS's ToInt32 will need one of them.
  • Memory and the rest:
    • f32; narrow loads and stores; the offset and align immediates;
    • memory.grow, memory.size and the bulk-memory ops;
    • globals; reference types and tables; SIMD.
  • Calls (call, call_indirect and return_call): the biggest gap. It decides how a multi-function Wasm blob is designed.
  • Stack-polymorphic dead code: Wasm accepts it and LIR rejects it.
  • NaN results: where Wasm allows several, LIR fixes one choice, which refines Wasm.

Not done

  • No mutations.json, no independent transcription and no conformance suite.
  • The Wasm spec isn't vendored, so the section numbers in the comments are from memory of release 2.0 and should be checked. The instruction and operator names are exact.

Verification

  • Verus, on a fresh target dir in WSL: verification results:: 34 verified, 0 errors. Breaking the load typing rule makes tc_sound fail, and changing the store-then-load example's expected value makes that example fail, so the proofs are not vacuous.
  • After rebasing onto Phase 7.3 (first half): the JS parser's spec and contracts #190: cargo metadata --locked, rustfmt, build, clippy -D warnings and cargo xtask check (STATIC CHECKS PASSED) all pass. The rebase changed only Cargo.lock and PLACES, so Verus was not re-run.
  • cargo xtask verify --changed was not run locally, because the new crate changes Cargo.lock. CI's full verification is the check, and its proof jobs need approval.

🤖 Generated with Claude Code

atiernan and others added 4 commits November 17, 2026 16:14
A new tier-0 crate with the abstract syntax (types, values, structured
instructions, bounds_check, region loads and stores, exit) and a fuelled
big-step semantics as a spec fn, transcribing the Wasm core 2.0
instructions it mirrors. Modelling choices are listed at the top of spec.rs.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
tc checks an instruction against the stack types, with Idx types for
bounds-checked indexes and no stack-polymorphic dead code. The soundness
theorem follows in the next commit.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
tc_sound: a well-typed instruction in a conforming state is never stuck
(so every load and store is inside its region), and its outcome conforms
to its typing. run_sound is the corollary for a function body. Also the
Wasm-coverage comparison and the gaps, as crate docs.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
A bounds-checked load, a countdown loop and a store-then-load, typed,
rejected when they should be (no check, a short check, dead code), shown
never stuck by tc_sound, and evaluated.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
atiernan and others added 2 commits November 17, 2026 20:21
CI's proof job requires a mutations.json for every crate Verus checks.
Three mutations of the typing (a load taking an unchecked index, Idx
subtyping reversed, `br` falling through), each killed by an existing
proven example.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
atiernan and others added 2 commits November 20, 2026 19:40
The branch-allows-dead-code kill certificate "did not build" in CI: typing
`br` goes through top_sub and stack_sub, whose pointwise `forall`
compute_only cannot evaluate. stack_sub is now defined by recursion on the
last element (same meaning), and soundness::lemma_stack_sub_pointwise proves
it equals the `forall` form, which the two lemmas that used that form now
call. This is the pattern clazel-pkcs1 uses for `two_to` against vstd's pow2.

Locally (Verus 0.2026.10.04): 36 verified, 0 errors; 3 mutations, 3 killed
by a theorem with certificates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch is being deployed

1 queued deployment
full-verification — 04cb003b Deployed Nov 20, 2026 by atiernan via Approve the proofs #619
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.

1 participant