Solid Snake

A statically typed, Python-flavored language with Rust-inspired guarantees, and the register-based bytecode VM it compiles to. The idea is a language that reads like Python but does not let you shoot yourself in the foot, running on a small hardened VM that stays boring and predictable underneath.

The name is a Metal Gear Solid nod. There is no stealth action here, just a VM that tries not to mess around.

What works today

The language is real and runs end to end. Current surface:

• Functions, recursion, if/while/for, and the usual arithmetic over Int, Float, Bool, and String.
• Structs (type) with methods, protocols with nominal conformance, and extend blocks.
• Generics: generic types and functions, monomorphized, including generic protocol bounds.
• Enums as tagged unions, match as both a statement and an expression, with exhaustiveness checking.
• Errors as values: Result, Option, a small Error enum, and the ? operator, all in the prelude.
• Collections: arrays, growable lists, and string-keyed maps, with for iteration over a shared iterator protocol.
• String processing primitives (byte_at, substring, len) with higher operations built on them in the prelude.
• A str conversion surface any user type can join by implementing Display.

The prelude (solid-snake-compiler/src/prelude.ss) is library code written in the language itself. Only the syntax that needs compiler support lives in Rust. Everything expressible in the language stays in the prelude, which keeps the native primitive layer thin.

Running a program

Run a source file:

cargo run -p solid-snake-compiler -- path/to/program.ss

Run a snippet inline:

cargo run -p solid-snake-compiler -- -c 'let x = 2 + 3
print(x)'

Useful flags:

• -i keeps an interactive session open after the file runs. Each line runs standalone for now, so indented multi-line blocks belong in a file.
• -v prints the lowered IR and decoded bytecode before running, for looking under the hood.
• --no-opt disables constant folding, so runtime code paths execute instead of being folded away at compile time. Handy for checking that the folded and unfolded builds agree.

Examples

The examples/ directory holds one runnable program per language feature. Run any of them the same way:

cargo run -p solid-snake-compiler -- examples/error_handling.ss

Example	Shows
fibonacci.ss	functions, recursion, while
control_flow.ss	if/else, loops
structs.ss	type definitions and fields
methods.ss	methods on types
shapes.ss	protocols and nominal conformance
generics.ss	generic types and functions
display.ss	the str/Display surface
error_handling.ss	enums, match, Result/Option, the ? operator
arrays.ss, lists.ss	fixed arrays and growable lists
maps.ss	string-keyed maps
iteration.ss	for over the iterator protocol
strings.ss	string processing
input.ss	reading input
resources.ss	reference counting and cleanup
values.ss	scalars and basic expressions
http_server.ss	a file server on std.http: a Handler type plus http_serve, a task per connection
poll_server.ss	concurrent connections on one thread, event-loop style over __poll

The examples double as integration tests. Each has a checked-in .out snapshot beside it (and an .in file when it reads input), and a golden test compiles and runs every example under both the folded and unfolded builds, requiring the two to agree with each other and with the snapshot:

cargo test -p solid-snake-compiler --test goldens             # verify
UPDATE_GOLDENS=1 cargo test -p solid-snake-compiler --test goldens   # bless intentional changes

Adding an example is: write the .ss, bless, and eyeball the new .out in the diff.

Building and testing

cargo build           # whole workspace
cargo test            # the full suite (VM and compiler)

When you add or change a VM opcode, regenerate the instruction docs or the doc-sync tests fail:

cargo run --bin docgen

Workspace layout

• solid-snake-vm: the register-based bytecode VM: instruction set, encoding, execution, heap with reference counting, and the builtin functions.
• solid-snake-compiler: the language front end and code generator: lexer, parser, type checking, monomorphization, IR, and bytecode generation. The prelude and the examples live here and at the repo root.
• solid-snake-vm-macros: the declarative macros that generate opcode bindings, encoding, and dispatch from instruction definitions.
• solid-snake-bytecode-file-format: the on-disk bytecode format.
• solid-snake-wasm: a wasm build of the VM for running in the browser, sandboxed away from the real system.

The VM underneath

The VM is register based and deliberately small. Values are raw u64 interpreted per instruction, with no global runtime typing. Memory is segment-indexed and every access is bounds checked. Calls follow a fixed convention (R0 for the return value, R1 upward for arguments) over a sliding frame stack. Types and safety are the compiler's job. The VM stays a plain, checkable execution layer, which is also what keeps a future native or C compilation target on the table.

Design notes and roadmap

Design work happens in docs before code. plans/ holds the detailed plans and the reasoning behind them, each written to be read cold:

• IO_DESIGN.md: the I/O and concurrency model (readiness-based, colorless, thin primitives).
• WEB_SERVER_TARGET.md: the medium-term north star, a small synchronous web server, and the pieces it needs.
• FILE_IO.md, TCP_NETWORKING.md: the file and network builtins toward that target.
• DECORATORS.md: compiler decorators and intrinsic builtin bindings.
• ERROR_HANDLING.md, MATCH_MATRIX.md: the error-handling arc and match coverage.
• ASSESSMENTS.md: the queue of larger design questions not yet acted on (AOT and C transpilation, a module system, refined types, inlining and tail calls).

Status

Early but real. The language runs, the test suite is green, and the near-term direction is file and network I/O toward a self-hosted small web server. Contributions and ideas are welcome, especially around the language front end, the standard library, and the eventual native compilation path.