T32 MCP Server

Simple Language

Simple is a self-hosted language and toolchain that combines a readable Python-like surface with compiler-integrated testing, documentation, architecture rules, and baremetal-oriented execution paths.

The repo is unusually broad: language, compiler, interpreter, loader, test runner, doc generation, traceability tooling, SDN-backed project databases, editor tooling, and hardware-oriented test flows all live together.

Quick Navigation: Distinctive Features | Feature Status | Quick Start | Language Basics | Examples | Editor Plugins | Documentation

---

Distinctive Features

• Self-hosted staged toolchain: real source layers for frontend, type analysis, borrow checking, backend, driver, interpreter, and loader live in-tree.
• Verification-native workflow: SSpec tests, the SPipe runner/docgen process, SDoctest executable docs, coverage, traceability checks, and generated spec docs are part of the toolchain rather than bolted on.
• MDSOC architecture support: virtual capsules, manifests, and architecture-aware repository structure are first-class concepts.
• Parser-friendly macro system: macro definitions, expansion, validation, and hygiene are compiler features rather than editor-hostile text substitution.
• Math-oriented syntax blocks: m{}, loss{}, and nograd{} are implemented syntax with parsing, evaluation, five rendering backends (text, debug, Unicode, LaTeX, Markdown), and editor integration (query/LSP hover, VSCode highlighting/preview, Neovim inline Unicode preview with conceal). The autograd path is complete for the promoted torch-backed C/LLVM scope.
• SDN-backed textual databases: tests, todos, dashboards, and other project metadata are stored through repo-native SDN data flows.
• Multiple execution paths: interpreter, loader, SMF/module loading, and native/LLVM-oriented compilation paths coexist in one system.
• Baremetal-oriented build and test plumbing: QEMU, semihosting, MMIO mailbox, remote baremetal flows, and adapter-backed hardware lanes (8 authoritative) are built into the repo story.
• Tooling-aware language rules: Tree-sitter integration, primitive-public-API linting, traceability tooling, and language statistics are part of the platform.
• Shared UI contract across supported surfaces: one HTTP-based test protocol (Protocol V1) with UITestClient drives both the web backend and the TUI-web proxy through a shared handle_test_request handler, verified by a cross-surface contract suite. Contract: doc/04_architecture/shared_ui_contract.md

Feature Status Highlights

Implemented and safe to advertise:

• SSpec tests, SPipe runner/docgen, SDoctest, coverage, traceability checks, and generated spec docs
• SPipe mock policy: system-test mock ban, HAL-only and custom pattern modes
• Self-hosted staged compiler, interpreter, and loader architecture
• MDSOC manifests and architecture-focused project structure
• Parser-friendly macros with validation and hygiene
• Tree-sitter outline/query tooling
• SDN-backed project, test, and todo databases
• Primitive-public-API linting and semantic wrapper/unit-type patterns
• Borrow-checking infrastructure
• Watch mode and auto-build support
• mmap-backed loader support and executable-memory plumbing
• Baremetal build/test plumbing and host-aware remote baremetal flows
• C/C++ bidirectional SFFI for the supported ABI subset: exports, imports, callback trampolines, layout verification, and round-trip proof tests

Implemented, but best described with qualifiers:

• LLVM full-family closure is complete for the declared public matrix: every llvm-lib and llvm backend row is now explicitly stable or unsupported, with no ambiguous middle states. rust-llvm remains a bootstrap-only seed path outside the public family claim
• Lean verification workflow is complete for the supported verification subset: deterministic Lean generation, proof artifact inventory, Lean/Lake checking, cache invalidation, and verification-state reporting. Contract: doc/04_architecture/lean_verification_contract.md. Report: doc/09_report/lean_verification_complete_2026-04-04.md
• GC and no-GC runtime families: 5 public families (common, nogc_sync_mut, nogc_async_mut, gc_async_mut, nogc_async_mut_noalloc) with compiler boundary enforcement, interpreter warnings, and target preset mapping. Support matrix: doc/04_architecture/runtime_family_support_matrix.md
• Shared UI contract across web backend and TUI-web proxy (Protocol V1): shared handler, structured error model, stable element IDs, cross-surface contract suite — but this is a shared test protocol, not a full unified UI rendering layer
• Remote baremetal execution has 8 authoritative lanes (3 stable + 5 host-aware including both GHDL semihost and mailbox simulation), but hardware-dependent lanes remain host- and board-aware rather than universally complete. Lane matrix: doc/08_tracking/lane_matrix.md

Implemented with bounded scope:

• m{} / loss{} / nograd{} are complete for the promoted torch-backed C/LLVM scope, including backward, detached-input failure, and nograd{} restore semantics. Other backends remain deferred
• AOP provides predicate-based pointcuts (execution, within, attr), deterministic before/after/around advice, compile-time weaving as the default backend, and scoped runtime interception. Support matrix: doc/05_design/aop_support_matrix.md
• VHDL backend compiles a documented hardware-oriented Simple subset to synthesizable VHDL-2008, validated through GHDL analysis/elaboration. Strict fail-fast on unsupported constructs. Two GHDL RV32 simulation lanes are operational: semihost (GDB-backed, ARM semihosting traps) and mailbox (debugger-independent, MMIO at 0x80FF0000 with ram_sentinel result collection). Support matrix: doc/04_architecture/vhdl_support_matrix.md. Mailbox protocol: doc/04_architecture/ghdl_rv32_mailbox_protocol.md

Implemented:

• Anti-dummy / anti-stub enforcement is active on the primary source and compiled CLI surfaces (simple lint, simple verify quality). All public-facing proof suites (SFFI, T32 hardware, compiler/runtime/system) now pass the gate. Remaining debt is only in deferred OS/GPU/experimental areas — all active surfaces are clean.

See doc/report/unique_features.md for the evidence-backed audit.

---

Runtime Families

Simple organizes its standard library into runtime families based on allocation, mutation, and concurrency requirements:

The compiler enforces family boundaries: importing a GC module from a no-GC context produces a diagnostic warning. Target presets (Baremetal, Hosted, EmbeddedWithHeap) automatically restrict module resolution to compatible families.

For advanced use: nogc_async_immut provides persistent data structures with lock-free concurrency.

See Runtime Family Support Matrix for full contracts, and Known Limitations for current caveats.

---

Quick Start

Installation

What you get:

• Complete Simple compiler and toolchain source
• Standard library and generated spec manuals
• Development tools, including MCP server, LSP, and debugger surfaces

Use a source checkout for the current beta. It also initializes the example and tooling submodules used by the docs and tests:

git clone --recurse-submodules https://github.com/ormastes/simple.git

cd simple export PATH="$PWD/bin:$PATH" simple --version

For an existing checkout:

git submodule sync --recursive

git submodule update --init --recursive

Note: Rust remains present as the bootstrap seed and host substrate. Product compiler, library, and tool work should stay in Simple source wherever the repo can express it; do not read "pure Simple" as "there is no Rust source in this checkout" today.

Source Footprint

Snapshot generated 2026-04-23 from existing tracked .spl, .rs, .c, .h, .s, .S, and .asm files. Blank lines and comment-only lines are excluded; examples/ code is included; vendored and third-party source is excluded.

From Source (Developers Only)

Only needed if you want to modify the runtime:

scripts/setup/setup.shs

bin/simple build bootstrap

Direct commands behind the wrapper:

src/compiler_rust/target/bootstrap/simple --version

bin/simple build bootstrap sha256sum bootstrap/simple_stage2 bootstrap/simple_stage3

See doc/02_requirements/app/build/bootstrap.md and doc/03_plan/compiler/bootstrap/pure_simple_bootstrap_stage2_remaining_2026-05-04.md for the current bootstrap flow and remaining pure-Simple self-hosting notes.

Build with GPU Support

simple build --release --features=vulkan

Your First Program

# hello.spl

>> fn main() -> i64:

... 0 # Entry point, returns exit code

# Run it

simple hello.spl echo $? # Prints: 0

---

CLI Usage

The simple command works like Python:

Usage:

simple Start interactive REPL simple Run source file simple Run compiled binary simple -c "code" Run code string; statement snippets print only program output simple compile [-o ] Compile to SMF simple watch Watch and auto-recompile

Build System (Self-Hosting): simple build Build the project (debug) simple build --release Release build (optimized) simple build --bootstrap Bootstrap build (minimal 9.3MB) simple build test Run all tests simple build coverage Generate coverage reports simple build lint Run linter (clippy) simple build fmt Format code (rustfmt) simple build check Run all quality checks simple build clea