Mvm Documentation

Mvm is an experimental Go interpreter built from a pipeline of composable packages.

Guides

• Usage Guide -- CLI commands, execution tracing, the trap() debugger, remote imports, environment variables

Module Reference

• scan -- language-independent lexical scanner
• lang -- token types and language specification
• goparser -- Go parser producing flat token stream (no AST)
• symbol -- scoped symbol table
• comp -- bytecode compiler with peephole optimization
• vm -- stack-based bytecode virtual machine
• interp -- integration layer and REPL
• synth-types -- cross-cutting: how interpreted types project onto real reflect.Types and the invariants that keep them in sync
• runtype -- synthesizes Go rtypes carrying interpreted methods for native dispatch
• stdlib -- standard library wrappers for native Go imports
• stdlib/stubs -- method-shape catalog and dispatch-stub pools feeding runtype
• stdmod -- redirect FS that routes stdlib imports through the synthetic github.com/mvm-sh/std module
• modfs -- in-memory fs.FS over the Go module proxy for dynamic network imports
• cmd/extract -- generator for stdlib binding files
• cmd/mvmlint -- project-specific source linter built on mvm's own scanner

Architecture

• Architecture Overview -- pipeline design, data flow, and key design decisions

Architecture Decision Records:

• ADR-001: Flat token stream instead of AST
• ADR-002: Hybrid Value type
• ADR-003: Scope as slash-separated path
• ADR-004: Two-phase compilation with pre-allocated slots
• ADR-005: Per-type opcodes with immediate variants
• ADR-006: Native Go function interop (WrapFunc / MvmFunc)
• ADR-007: Super instructions and instruction fusion
• ADR-008: Goroutine and channel support
• ADR-009: Interface bridging for native Go calls
• ADR-010: Compiler intrinsics for math and bit manipulation
• ADR-011: Generics via monomorphization
• ADR-012: Package patchers and argument proxies
• ADR-013: Split stdlib bindings into core and ext
• ADR-014: Dynamic network imports via Go module proxy
• ADR-015: Absolute token positions throughout the pipeline
• ADR-016: Runtime introspection via *runtime.Func sentinels
• ADR-017: Synthetic std module + stdlib redirect FS
• ADR-018: Virtualized process exit via panic-based ExitError
• ADR-019: mvm test drives testing.MainStart(...).Run() directly
• ADR-020: Type references resolved by identity slot, not by name
• ADR-021: Synthesized rtypes for native method dispatch (supersedes ADR-009, part of ADR-012)
• ADR-022: Word-class ABI register shapes for method dispatch (extends ADR-021)
• ADR-023: Index-based method dispatch (accepted; phase 1 native tables + 2' fused method frame landed, embedding/direct phases already realized, 4 deferred)