M1 - First protect-and-rewrite path
The CLI rewrites supported static methods, preserves unsupported methods, and writes a sibling protected assembly.
Read the noteMirrorVM research notebook
Make the machine
easy to read.
Notes on .NET execution, virtual machines, and reverse engineering. MirrorVM development sits alongside the wider technical questions that help explain it.
01—06
Current notes
October 2026
From the notebook
Project notes
Six notes cover the M1 through M3 milestones, compatibility evidence, VM architecture, and interpreter design.
Compatibility is a target matrix, not a checkbox
What the protected sample and numeric CLR comparisons verified across Framework 2.0 through 4.8.1 and .NET Core 2.0 through .NET 10.
Read the noteHow MirrorVM executes a protected method
Follow CIL conversion, cached decoded programs, indexed dispatch, the VM value stack, and the shared return path.
Read the pageM2 - Numeric values end to end
How numeric kinds, arithmetic, conversions, and typed returns pass through the VM, with CLR comparisons across the x86 and x64 sample matrix.
Read the noteReducing repeated work in the interpreter
Before and after: indexed opcode dispatch, inline numeric stack values, and decoded bytecode cached for reuse—with performance limits stated plainly.
Read the noteM3 - Control flow
Translate short and long branches, comparisons, switches, and supported locals; validate stack flow and branch targets against original CLR output across the x86 and x64 sample matrix.
Read the noteResearch roadmap
Development milestones
Each release is a small checkpoint: add a capability, record evidence, and leave open questions visible.
-
✓
M1 - First protect-and-rewrite path
Convert a linear arithmetic and string method subset, execute it through the shared VM, and leave unsupported methods unchanged with a reported reason. The protected sample passed all 26 configured runtime matrix entries in x86 and x64 processes.
-
✓
M2 - Numeric values end to end
Carry signed and unsigned integers, native integers,
Single, andDoublethrough arguments, constants, arithmetic, conversions, and typed returns. Implement arithmetic, bitwise, shift, comparison,ckfinite, and the full CILconv.*family, including checked unsigned-source forms. CLR differential checks for implemented numeric opcodes and protected numeric methods passed all 26 configured matrix entries in x86 and x64 processes.Decimalis supported by value only; its arithmetic operators compile to calls. -
✓
M3 - Control flow
Translate short and long forms of
br,brtrue/brfalse, all signed and unsigned comparison branches, andswitch; support locals for implemented value kinds; validate branch targets, stack heights and kinds at merges, reachable fall-through,maxstack, and local assignment. The protected output matched the original CLR sample on all 26 configured matrix entries in x86 and x64 processes. -
M4 - Method calls and dispatch
Add call, callvirt, and object creation with argument and return handling. Cover overloads, virtual and abstract methods, interface dispatch, structs, generic methods/types, and the constrained. and tail. prefixes.
-
M5 - Exception handling
Translate exception regions, including nested catch, filter, finally, and fault clauses, then verify exception propagation, rethrow, and stack unwinding.
-
M6 - Toward broad CLR compatibility
Cover the remaining type system and CIL rules: Boolean and character values; every signed and unsigned integer width; native integers; floating point; Decimal, Half, Int128, and UInt128; enums; references, strings, objects, and boxing; nullable and arbitrary structs and layout; arrays of every rank; generics; managed byrefs/ref returns; unmanaged and function pointers; typed references; unsafe code; and async/iterator state machines. The final gate is the full version matrix below. Every milestone remains open until its behavior is built and run on every applicable target.
Current boundaries
Known limitations
Unsupported methods keep their original bodies and are reported with a reason.
- Method shapeStatic, non-generic methods without exception handlers; both value returns and
voidare supported. Argument indexes use CIL's 16-bit operand, with no lower 256-parameter MirrorVM cap. Parameter, return, and local types must be supported. - Signature typesBoolean, built-in integers through 64-bit,
IntPtr/UIntPtr,Single,Double,Decimal, andString. - InstructionsArgument and supported local loads/stores, numeric/string/null constants, arithmetic, bitwise, shifts, comparisons,
neg,not,ckfinite, numericconv.*,nop, short and long branches,switch, andret. Calls, fields, arrays, exception regions, and pointer/byref operations are unsupported. - Skipped methodsUnsupported methods remain unchanged with a reported reason. If no method qualifies, no protected output is written.
- ValidationStack validation covers only the implemented CIL subset; it is not a full ECMA-335 verifier. Unsupported instructions and incompatible control-flow states keep the original method body.
- Numeric behaviorEvery implemented numeric opcode has CLR differential coverage on each matrix runtime, including signed and unsigned integer boundaries, checked and unchecked overflow, division/remainder edges, out-of-width shifts, conversion boundaries, signed zero, subnormals, finite extrema, infinities, and NaN. Framework x86 uses
Doubleintermediates forSinglestack arithmetic; x86 shift handling also matches the observed Framework and Core 2.0 CIL behavior. These are targeted cases, not a complete numeric proof.Decimalpasses by value, but its operators compile to unsupported calls;Half,Int128,UInt128, enums, arbitrary structs, and other stack kinds remain outside this milestone. - Inputs and runtimeAssemblies with strong-name public keys, mixed-mode assemblies, and native apphosts are rejected. Pass modern .NET apps as managed DLLs; keep
MirrorVM.Runtime.dllbeside the output. - Compatibility evidenceThe protected sample matched original CLR output on all 26 configured matrix entries in x86 and x64 processes. Framework 4.x ran on the installed 4.8.1 in-place CLR; those entries do not prove behavior on each historical 4.x runtime separately.
Working premise
Clarity is part
of the design.
MirrorVM is a human-guided, vibecoded experiment in how far AI can help build a small VM. It is intentionally simple for learning and research, not a product. Releases will add narrow capabilities as research checkpoints, with tests and open questions documented so readers can follow how the project develops.
Start with the current virtualizer