Goruntime Kernel

Native Go WebAssembly Engine for GoRuntime Studio — high-fidelity simulation of Go runtime internals (GMP scheduler, channels, memory allocator, GC) compiled to WebAssembly and bridged to Svelte 5 via a zero-copy binary event protocol.

---

🎯 Purpose

goruntime-kernel is the computational core of GoRuntime Studio. It replaces the legacy TypeScript-based simulation engine with a native Go runtime compiled to WebAssembly, delivering:

• 100% semantic fidelity — real Go code for hchan, sudog, G/M/P scheduling, and memory management
• 60 FPS performance — zero-allocation binary event streaming via SharedArrayBuffer RingBuffer
• Deterministic time-travel debugging — memory snapshots for stepping forward and backward through execution

---

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│  SVELTE 5 STUDIO UI                                                         │
│  ┌─────────────────┐    ┌─────────────────────────┐    ┌───────────────┐    │
│  │ Header.svelte   │───▶│ timeline.store.svelte.ts│───▶│CanvasView.slt │    │
│  │ Controls & Step │    │ State, History & Issues │    │ 2D Graph Nodes│    │
│  └─────────────────┘    └─────────────────────────┘    └───────────────┘    │
│           │                        ▲                           ▲            │
│           │ Dispatch Command       │ Update Reactive Nodes     │            │
│           ▼                        │                           │            │
│  ┌─────────────────────────────────────────────────────────────┐            │
│  │ sync.bridge.ts — Binary Event Decoder & State Sync          │            │
│  └─────────────────────────────────────────────────────────────┘            │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │ Invoke Exported Functions
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  GO WASM ENGINE SANDBOX                                                     │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ Wasm Control API (cmd/wasm/main.go)                                 │    │
│  │ stepSend, stepReceive, spawnGoroutine, createSnapshot, restoreSnap  │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│           │                        │                        │               │
│           ▼ 1. Trigger Execution   ▼ 2. Save/Restore        ▼ 3. Channel Ops│
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ GO ENGINE CORE (pkg/)                                               │    │
│  │ ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌──────────────┐ │    │
│  │ │ pkg/gmp     │  │ pkg/memory  │  │ pkg/channels│  │ pkg/snapshot │ │    │
│  │ │ Scheduler   │  │ Virtual Mem │  │ hchan/sudog │  │ Serialization│ │    │
│  │ │ G, M, P     │  │ MHeap/MCache│  │ Wait Queues │  │ Time-Travel  │ │    │
│  │ └─────────────┘  └─────────────┘  └─────────────┘  └──────────────┘ │    │
│  │           │                        │                        │       │    │
│  │           ▼ 3. Emit State Changes  ▼ 4. Emit Events         ▼       │    │
│  │  ┌─────────────────────────────────────────────────────────────┐    │    │
│  │  │ pkg/eventstream — 16-byte Binary Event Streamer             │    │    │
│  │  │ Fixed packets: G-M-P, Sudog, GC, Memory Alloc               │    │    │
│  │  └─────────────────────────────────────────────────────────────┘    │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                    │ 4. Push Binary Events                  │
│                                    ▼                                        │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ SharedArrayBuffer — Atomic RingBuffer Event Queue                   │    │
│  │ Zero-copy, lock-free, 60 FPS                                        │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘

---

📦 Binary Event Protocol

All communication between the Go Wasm kernel and the Svelte 5 UI occurs through a 16-byte fixed-size binary packet written into a SharedArrayBuffer RingBuffer.

16-Byte Packet Layout

Offset	Size	Field	DataView Type	Description
0–1	2 B	EventOp	uint16	Operation code (spawn, park, chan send, mem alloc, etc.)
2–5	4 B	EntityID	uint32	Primary entity ID (Goroutine G, Channel hchan, etc.)
6–9	4 B	TargetID	uint32	Secondary / target ID (Processor P, sudog, address)
10–13	4 B	ValueState	uint32	Value, state, stack size, GC color, flags
14–15	2 B	Sequence	uint16	Monotonically increasing timeline step counter

EventOp Codes

Code	Name	Semantics
0x0001	EV_G_SPAWN	New goroutine G created (Gidle → Grunnable)
0x0002	EV_G_SCHEDULE	Goroutine assigned to Processor P (Grunnable → Grunning)
0x0003	EV_G_PARK	Goroutine parked / blocked (Grunning → Gwaiting)
0x0004	EV_G_UNPARK	Goroutine unblocked (Gwaiting → Grunnable)
0x0005	EV_G_DIE	Goroutine execution completed (Grunning → Gdead)
0x0010	EV_CHAN_SEND	Successful send into hchan
0x0011	EV_CHAN_RECV	Successful receive from hchan
0x0012	EV_CHAN_BLOCK	Blocking on channel, sudog enqueued
0x0013	EV_CHAN_UNBLOCK	sudog removed from wait queue, G unblocked
0x0020	EV_MEM_ALLOC	Heap allocation via MCache / MSpan
0x0021	EV_STACK_GROW	Stack expanded, copystack executed
0x0022	EV_GC_MARK	Object marked during tri-color GC phase

RingBuffer Header (first 16 bytes of SharedArrayBuffer)

Offset	Size	Field	Description
0–3	4 B	HeadIndex	Next write position (updated by Go Wasm)
4–7	4 B	TailIndex	Last read position (updated by TypeScript)
8–11	4 B	Capacity	Max number of events in buffer (e.g. 4096)
12–15	4 B	DroppedEvents	Counter of lost events on overflow

---

🚀 Quick Start

Prerequisites

• Go 1.23+
• Node.js 20+ (for frontend bridge and tooling)

Build the Wasm Engine

# Clone the repository
git clone https://github.com/DenysSkobalo/goruntime-kernel.git
cd goruntime-kernel

# Compile Go engine to WebAssembly
make build-wasm
# → dist/engine.wasm

Run Quality Checks

# Full pre-flight check (format, lint, test, build)
make check

# Individual targets
make test      # Run Go unit tests
make bench     # Run benchmarks
make lint      # Run golangci-lint
make fmt       # Format Go source files
make clean     # Remove build artifacts

Integrate with GoRuntime Studio

Copy the generated artifact into the Studio frontend:

cp dist/engine.wasm ../goruntime-studio/public/

The Svelte 5 bridge (sync.bridge.ts) will automatically load the Wasm module and begin polling the SharedArrayBuffer RingBuffer at 60 FPS via requestAnimationFrame.

---

📁 Project Structure

engine/
├── cmd/wasm/main.go          # Wasm entrypoint, syscall/js bindings
├── pkg/
│   ├── eventstream/            # Binary Event Encoder & SharedArrayBuffer RingBuffer
│   ├── gmp/                    # Scheduler Engine (G, M, P queues, Work-Stealing)
│   ├── channels/               # Channel Logic (hchan, sudog, WaitQ)
│   ├── memory/                 # Virtual Memory Layout (MHeap, MCache, copystack, GC)
│   └── snapshot/               # Memory Snapshot & Serialization Engine
├── go.mod
├── go.sum
├── Makefile                    # Build, test, lint, format automation
├── .golangci.yml               # Linter configuration
├── package.json                # Node tooling (husky, commitlint, lint-staged)
└── .github/workflows/ci.yml    # GitHub Actions CI pipeline

---

📄 Documentation

Document	Purpose
DEVELOPMENT.md	Deep-dive engineering spec: RingBuffer algorithms, GMP scheduler, channels, memory, snapshots
CONTRIBUTING.md	Contribution guidelines: branching model, GoDoc standards, Conventional Commits, PR checklist
SECURITY.md	Security policy and vulnerability disclosure
ADR-001	Architectural Decision Record: migration from TS to Go Wasm
TES-001	Technical Engine Specification: binary protocol, component APIs, migration plan

---

🤝 Contributing

We welcome contributions! Please read CONTRIBUTING.md for our branching model, code standards, and PR process.

All PRs must target the develop branch and pass make check.

---

📜 License

MIT License © 2026 Denys Skobalo