Soma VM

Lightweight WASM/WASI runtime for Wetware processes (procs).

---

Overview

Soma VM hosts Wetware processes — actor-style WASM/WASI modules that consume streamed messages via stdin and maintain internal state.

Key design principles:

• Actor model: Each proc is a WASM/WASI module identified by a stable 160-byte PID.
• Local Only: Designed to be embedded in P2P routing layer for distribution.
• Streaming messages: Messages are streamed chunk-by-chunk into proc’s stdin with no buffering outside the proc's linear memory.
• Synchronous processing: Procs process one complete message at a time.
• Explicit message boundaries: End of message is signaled by a guest export function call (flush()), not by EOF.
• Gas metering & cooperative yielding: Procs start with a gas budget and must call the host export recharge() to yield and request more gas.
• Trap on gas exhaustion: If gas runs out without recharge, proc execution is terminated.

---

Core Concepts

Wetware Process (Proc)

• Stateful WASM/WASI module.
• Identified by a 160-byte PID.
• Receives streamed messages via stdin.
• Processes messages synchronously, one at a time.

Message Streaming Interface

• MessageBuffer.write(chunk: Data) streams chunks directly into proc stdin.
• MessageBuffer.flush() signals the proc to consume the buffered message (calls guest flush() export).
• MessageBuffer.reset() aborts current message buffering and discards partial data.

Gas Metering and Scheduling

• Each proc is provisioned with a finite gas budget.
• Guest code calls recharge() host export to yield and request additional gas.
• Gas exhaustion triggers a trap, terminating the proc.
• Enables cooperative multitasking and resource control.

---

License

TBD