Bytecode VM

[ImTheSquid]

This PR merges my experiment rhaigrain into the main Rhai repo under the grain module and feature flag, requested as an alternative to #1108. It will be marked as experimental. This PR also updates the Rust edition to 2021 from 2018 to support some operations that were previously forbidden by the borrow checker (such as split mutable borrows). The MSRV was not changed.

[schungx]

There are some failed CI tests... Can you look into them?

All in all, surprisingly few global impact for such a large feature! The changes are all localized and we'll packaged.

[Copilot]

Pull request overview

This PR introduces an experimental, feature-gated (“grain”) bytecode VM into Rhai, including artifact (de)serialization, verification, and extensive differential/fuzz-style test harnesses. It also updates the crate to Rust 2021 edition to enable newer borrow-checker capabilities needed by the implementation.

Changes:

• Add grain module behind a new grain feature flag, exposing Compiler, Program, and Vm, plus on-the-wire artifact read/write and verification.
• Add a dedicated grain integration test harness and fixtures, plus fuzz targets for hostile-bytecode loading and compile→write→read→run roundtrips.
• Bump Rust edition to 2021 and add supporting internal API exposure (Engine::get_indexed_mut to pub(crate)).

Reviewed changes

Copilot reviewed 42 out of 46 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
.gitignore	Ignore .zed/ editor directory.
Cargo.toml	Switch to Rust 2021, add grain feature, wire grain-only tests, extend fuzz feature to include grain.
fuzz/Cargo.toml	Enable grain feature for fuzz crate; add new fuzz bins; strengthen release profile checks.
fuzz/fuzz_targets/generated.rs	Grammar-directed fuzz target comparing VM vs walker.
fuzz/fuzz_targets/load.rs	Fuzz target for hostile artifact bytes into Program::read and VM execution.
fuzz/fuzz_targets/roundtrip.rs	Fuzz target for script compile→write→read→run parity vs walker.
src/eval/chaining.rs	Make Engine::get_indexed_mut pub(crate) for grain VM use.
src/lib.rs	Export pub mod grain behind #[cfg(feature = "grain")].
src/module/mod.rs	Whitespace cleanup in docs for with_params_info.
src/grain/mod.rs	New grain module root; forbids unsafe_code; exports Compiler, Program, Vm.
src/grain/bytecode/mod.rs	Bytecode module surface (ops, pools, verifier, assembly/disassembly).
src/grain/bytecode/chain.rs	Chain representation (Root/Step/Tail) for lvalue/rvalue chaining semantics.
src/grain/bytecode/chunk.rs	Chunk metadata (entry/end/max_stack) and ops iterator.
src/grain/bytecode/code.rs	Bytecode encoding/decoding, assembly/disassembly, switch target resolution.
src/grain/bytecode/op.rs	Opcode model and operand decoding helpers.
src/grain/bytecode/positions.rs	Position table representation and compact encoding/decoding integration.
src/grain/bytecode/strings.rs	String table representation borrowing names from artifact bytes.
src/grain/bytecode/switch.rs	Switch dispatch using Rhai’s hashed case semantics with seed probing.
src/grain/bytecode/verify.rs	Verifier ensuring structural safety before VM executes borrowed code bytes.
src/grain/compile/mod.rs	AST→bytecode lowering pipeline (compiler).
src/grain/compile/cases.rs	Range-arm splitting for switch dispatch table generation.
src/grain/compile/poolable.rs	Constant-pool eligibility rules for cross-process artifact safety.
src/grain/compile/slots.rs	Local slot assignment model aligned with Scope behavior.
src/grain/format/mod.rs	Artifact container format (header/sections), Cursor, varint helpers.
src/grain/format/abi.rs	ABI fingerprinting (widths + restriction feature flags) and mismatch reporting.
src/grain/format/read.rs	Artifact parsing into a Program, including safety checks + verification.
src/grain/format/write.rs	Artifact writer with explicit refusal modes for unsupported constructs.
src/grain/pos/mod.rs	No-std-friendly address→(line,col) resolver for stripped diagnostics.
src/grain/pos/varint.rs	LEB128/zigzag varint codec for position tables.
src/grain/program.rs	Program container for pools/chunks/code/positions plus helpers used across VM/compiler/format.
src/grain/vm/mod.rs	VM execution engine over verified bytecode, reusing host Engine for dispatch.
src/grain/vm/callback.rs	Runtime wrapper module enabling Rhai-native callbacks into compiled grain chunks.
tests/mod.rs	Grain integration test harness entry point (feature-gated via Cargo test config).
tests/grain/allocation.rs	Allocation/peak tracking harness (separate binary due to global allocator).
tests/grain/callback.rs	Tests for native-to-compiled callback behavior and known divergences.
tests/grain/corpus/mod.rs	Differential corpus definitions/utilities.
tests/grain/corpus/generate.rs	Deterministic script generator used by tests + fuzz targets.
tests/grain/differential.rs	Corpus-based differential testing between walker and VM.
tests/grain/fixtures/follow.rhai	Realistic fixture script for AST sizing/projection/allocation tests.
tests/grain/fixtures/golden.rgrn	Golden artifact fixture for format stability tests.
tests/grain/fixtures/golden.rhai	Source for the golden artifact fixture.
tests/grain/format.rs	Artifact format and robustness tests.
tests/grain/fuzz.rs	Seeded mutation/structural fuzz tests for loader+VM safety and parity checks.
tests/grain/limits.rs	Tests ensuring compiled code respects operation limits and progress interrupts.
tests/grain/projection.rs	AST-node pricing projection against planned stack encoding (internals-only).
tests/grain/scope.rs	Tests covering scope semantics and closure pointer differences.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[schungx]

Final thoughts: Do you suggest creating a new branch for it? Or just merge into main?

Actually merging into main shouldn't be a problem as the changes are extremely localized (other than the fuzzing part). But of course a separate branch would allow for testing new ideas with more extensive changes, such as to compile dynamically-loaded script modules. I suspect for that to happen, there'll be more changes in the core types in Rhai to accommodate bytecode script definitions in modules, or to even load modules which are pre-compiled into bytecodes.

And, as I mentioned in Discord, should we call the feature bytecodes instead of grain? The benefit of using grain is that we can add new VM engines or bytecode formats later on. The downside is the user must be educated on what grain is.

[ImTheSquid]

I think pushing to main is fine, it's gated behind a feature flag and doesn't have an impact on the rest of the code. We can always improve it in a branch when we inevitably find ways to do so, and I agree that deeper changes may be needed anyways to get really big features like the ones you mentioned. I think keeping the name as grain makes sense since this is an enclosed feature (bytecodes, vm, compiler) coming from rhaigrain, whereas bytecodes kinda buries the lede on what is actually contained within the module. All it takes is looking at the module docs to know exactly what it is.

[schungx]

Sorry, I just edited my last comment but you might have already read it.

Basically two questions:

• grain or bytecodes (or vm) as feature name (and src tree root name)

• new branch or merge into main

[ImTheSquid]

I think grain, also because internally it has mods both named bytecode and vm so it would be a bit clunky with those names. I also think merging to main is fine in this case, nothing changes for users who don't care to use it.

[schungx]

CI caught a bug in 32-bit integers mode...

[schungx]

A question: right now, how does the user use this thing?

Something like the following?

let code = engine.compile_into_grain(&ast)?;
let result = engine.eval_grain_with_scope(...)?;

[ImTheSquid]

Example now in the grain module header

[schungx]

OK, one final round of CI...

[ImTheSquid]

wait need to make sure it compiles under no_std, i think there are a few lingering items

[schungx]

@ImTheSquid I just found out that the unchecked and no_position features would conflict with grain. There are a bunch of methods not available when unchecked or no_position is set.

Also, I ran the bench (without unchecked and no_position which I might turn on for benchmarking):

                            walker          vm   speedup   floor   spread walker-slow  fragments
tight integer loop         106.0ms      54.4ms     1.95x   1.30x      29%     194.0ms          0
float arithmetic           537.8ms     272.4ms     1.97x   1.10x      83%     405.9ms          0
script fn calls             90.8ms      51.2ms     1.77x   1.55x      40%     106.0ms          0
switch, 4 arms             145.4ms      83.7ms     1.74x   1.40x      22%     261.3ms          0
switch, 16 arms            136.3ms      78.1ms     1.75x   1.35x      13%     283.3ms          0
branch heavy               197.8ms     107.9ms     1.83x   1.45x      12%     414.1ms          0
native callbacks            13.5ms      62.3ms     0.22x   0.25x       9%      19.8ms          0

So it seems roughly 2x speedup can be expected!

[schungx]

I see in the code that Vm::call_fn_with_options is not supported for binding the this pointer.

That would be a pretty severe limitation... I personally use it quite a lot, and it is very common for call_fn to be used in calling event drivers, all of which are written as functions with the context bound to this.

Is there a particular reason why it cannot be supported?

[ImTheSquid]

That was just me not wanting to deal with how to deal with this in stack frames, I'll see how easy it could be to do. I'll also try to fix unchecked and no_position, then merge. I think import is a pretty big job so I'm gonna end scope here and do import, custom syntax, and eval in a separate PR.

[ImTheSquid]

Lots of stuff here regarding making this work properly, but should be all good now. Also fixed the the feature flag compilation.

[schungx]

I see the six new opcodes needed to make this work. Is this due to the fact that this = v will failed before evaluating v if this is unbound?

Rhai did it this way to fail early and save some cycles. However we can consider this an implementation detail and Rhai can probably be changed to make it easier on the VM. This, the VM can evaluate v before finding out this does not have a target. That may remove a lot of the complications...

Also, not sure why it is so, but I've tried declaring functions that use this and using it with the VM, which worked perfectly. So the VM must be able to handle function methods before.

[ImTheSquid]

That's the reason for the REQUIRE_THIS opcode, the others are just used in the process of dealing with the semantics of this in the context of the stack environment where it kinda needs to be passed around like a hot potato lol. It's only a single opcode and a simple check so it's probably fine, but maybe it is unnecessary. It really depends though because if the function is native/impure then that could change a lot. The VM had some bad behavior that would allow some instances of this through and block others, now it consistently works with all of them.

[schungx]

One more thing. I see you lifted the syntactic fn names out as an independent function and call that in each of the entry points.

Beware that some of these entry points cross call each other, so we may be checking for syntactic function names more than once in a single call.

That probably would not affect performance but it would still be wise to avoid it as function calls are done a lot in Rhai... All operators are function calls.

[ImTheSquid]

Yeah that was just out of caution, it can be optimized later if necessary but before stuff like type_of would fail in very weird ways due to how dispatching works.

[schungx]

Ah, too late to raise the last issue. No worries, we can handle it later.