Skip to content

Phase 7.4: the bytecode and its Verus semantics (spec only) - #180

Open
atiernan wants to merge 8 commits into
claude/js-lexer-implfrom
claude/js-vm-spec
Open

atiernan wants to merge 8 commits into
claude/js-lexer-implfrom
claude/js-vm-spec

Conversation

@atiernan

Copy link
Copy Markdown
Member

Phase 7 item 7.4: the bytecode instruction set and its Verus semantics, spec fn step. The spec and the op list are committed together, before any handler or compiler code (rule 3). jit.md's front-end proofs will refine this spec.

Stacked on #176. Merge that PR first, or retarget this one to main afterwards.

What's here

crates/clazel-js-vm is a new crate: tier 0, depending only on vstd and on no browser crate.

  • src/ops.rs: the op list, in three classes.
    • Core ops never call a handler: moves, constants, this/callee/argc, and the undefined and nullish jumps.
    • Guarded ops run fast_step when fast_path(s, op) holds, and the handler otherwise: arithmetic, bitwise ops, comparisons, JumpIfTrue and JumpIfFalse, Loop, the TDZ check, property and element get and set with inline caches, Call and Return, and environment slots. The JIT inlines the fast path and exits otherwise.
    • Handler ops always call their handler: allocation, loose equality, typeof, globals, new, iteration, yield and await, and throw. HandlerId doubles as the JIT's exit code.
  • src/spec.rs:
    • Values: NaN-boxed u64s. A double is itself with NaN canonicalized; int32, the specials, heap references (u32 index plus u16 generation) and raw values are tagged in the NaN space.
    • Machine state: the frame region, fp, pc, the heap as an abstract map, code, inline caches, the pending exception and the termination flag.
    • step: written as if fast_path { fast_step } else { handler(..) }, where handler is an uninterpreted spec fn. There are no axioms.
    • Number semantics: ES's special cases are transcribed with step numbers. Only the rounding of an exact finite result is left uninterpreted.
  • src/lemmas.rs proves:
    • NaN-boxing round trips;
    • core ops keep state_wf;
    • core ops never take the handler, and handler ops always do;
    • a few Number facts.

For the spec reviewer, first

  1. The fast_path conditions for Call, Return, GetProp and GetElem, since the JIT's guards must equal them.
  2. The frame layout: four header slots, with the return address packed as a raw value (caller base and caller pc, 24 bits each). That limits the region to 2^24−1 slots, and a function to 2^24−1 ops.
  3. Result encodings: an int32 when both operands are int32 and the result fits (and is not -0). Div always gives a double.
  4. The Core, Guarded and Handler split.
  5. handler has no contract here. What the JIT needs from handlers becomes their contracts in 7.8.

Erratum

  • The problem: read literally, Number::multiply (§6.1.6.1.4) returns +0 for +0 × -5 and -5 × +0, because steps 4 and 5 only handle -0. 𝔽(0) is +0, but IEEE 754 and every engine give -0. I checked this against the pinned text.
  • What we specify: number_multiply implements the evident intent. It is recorded in docs/ERRATA.md, with "Reported upstream: not yet".

Known gaps

  • Guarded fast paths and Call/Return are not yet proven to preserve state_wf; only core ops are.
  • Two Number examples Z3 would not prove were removed: f64_of_int(1) and to_int32(2^31). Their formulas were checked against real doubles.
  • The uninterpreted f64_*_finite rounding functions will need a TCB entry when the JIT lands: the hardware's addsd and its siblings must agree with them.

Verification

  • Verus, on a fresh target dir in WSL: verification results:: 67 verified, 0 errors.
  • cargo xtask check: STATIC CHECKS PASSED. cargo build -p clazel-js-vm and clippy -D warnings are clean.
  • 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

Spec first (rule 3), no handlers and no compiler. The crate depends on
vstd only.

- ops.rs: the instruction set (register moves, constants, int32 and
  double arithmetic, comparisons, branches, property get/set with an
  inline-cache index, element get/set, calls and returns, closures,
  environment access, iteration, generator suspend and resume, throw),
  each op classed Core, Guarded or Handler, and the handler it calls.
- spec.rs: NaN-boxed u64 values (encode and decode), ECMA-262 Number
  operations on IEEE 754 bit patterns (pinned commit 0248456c), the
  abstract machine (frames as windows of the value-stack region, pc, heap
  as a map, inline-cache tables), `fast_path`, `fast_step`, the
  uninterpreted `handler`, and `step`. Modelling choices are listed at the
  top of the file.
- lemmas.rs: encode/decode round trips, op classes, core ops keep the
  machine well-formed, Number comparison properties.
- docs/ERRATA.md: Number::multiply gives +0 for +0 * -5.

Verus: 67 verified, 0 errors. Tier stays 0; nothing here is an
implementation.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
atiernan and others added 2 commits November 16, 2026 23:18
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@atiernan
atiernan changed the base branch from claude/js-jit-compiler-next-21ddc8 to claude/js-lexer-impl November 17, 2026 13:11
@atiernan
atiernan added this pull request to stack #188 November 17, 2026 13:11
atiernan and others added 2 commits November 17, 2026 20:19
CI's proof job requires a mutations.json for every crate Verus checks.
Three mutations of Number::multiply's zero signs (steps 4.b, 5.b and
the step 5a erratum), each killed by lemma_multiply_zero_signs, a new
lemma that evaluates the four zero-product cases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The mutation tool checks a kill certificate in its own module, and
Verus evaluates every compute_only assert of that module first. The
zero-product lemma evaluated in lemmas.rs, so each mutant would stop
Verus before its certificate ran. It moves to examples.rs, as in
clazel-base64, and the certificates call it from there.

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

This branch is being deployed

1 queued deployment
full-verification — 5f3a3b91 Deployed Nov 20, 2026 by atiernan via Approve the proofs #620
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