Moxie Architecture

Core Principle

The server is dumb. The client is smart. Each domain is sovereign.

Moxie enforces isolation at the language level. Domains are OS processes. There is no shared memory. Communication is serialized over IPC. Within each domain, goroutines cooperate on a single thread.

Compilation Pipeline

Moxie source (.mx files)
    │
    ▼
loader (package loading, MOXIEROOT overlays)
    │
    ▼
cgo (libclang processing for C interop)
    │
    ▼
SSA construction (via golang.org/x/tools/go/ssa)
    │
    ▼
compiler (Moxie SSA → LLVM IR)
    ├── spawn builtin → runtime.spawnDomain (Codec validation)
    ├── restriction checking: reject new, complex, etc.
    ├── goroutine lowering: go → task.start
    └── syscall intrinsics: inline assembly
    │
    ▼
transform (LLVM IR optimization passes)
    │
    ▼
interp (compile-time partial evaluation)
    │
    ▼
builder (orchestration)
    ├── compile musl, bdwgc, compiler-rt
    ├── compile extra .c files (signal.c, spawn_unix.c)
    └── link with ld.lld
    │
    ▼
Static ELF/Mach-O binary

For the JS target, jsbackend replaces the LLVM path:

Moxie SSA → jsbackend → JavaScript + jsruntime

Cooperative Scheduler

Each domain runs scheduler = "tasks" — a cooperative FIFO scheduler.

                ┌──────────┐
                │ Run Queue │ (FIFO)
                └─────┬────┘
                      │
          ┌───────────┼───────────┐
          ▼           ▼           ▼
     ┌────────┐  ┌────────┐  ┌────────┐
     │ Task 0 │  │ Task 1 │  │ Task 2 │
     │ stack  │  │ stack  │  │ stack  │
     └────────┘  └────────┘  └────────┘

• Tasks yield at channel operations (chan.go) and Gosched()
• Context switch via assembly (task_stack_amd64.S, task_stack_arm64.S)
• task.Pause() suspends the current task, task.Resume() re-queues it
• No preemption, no timer interrupts, no signal-based stack inspection
• Mutexes and atomics are no-ops (mutex-cooperative.go, atomic-cooperative.go) — single thread

Spawn: Domain Creation

spawn is a language builtin (like make, append). The type checker validates argument count and types. The SSA validator enforces moxie.Codec on all data arguments and channel element types.

spawn(fn, args...)
    │
    ▼ (compile time)
compiler/spawn.go
    │ validate all args implement moxie.Codec
    │ reject pointers, interfaces, functions
    │ emit: runtime.spawnDomain(wrapper, packedArgs)
    │
    ▼ (runtime)
src/runtime/spawn.go
    │
    ├── socketpair(AF_UNIX, SOCK_STREAM) → fds[2]
    ├── fork()
    │
    ├── child (pid == 0):
    │   ├── close(fds[0])
    │   ├── drain parent run queue
    │   ├── task.start(wrapper, args, 8KB)
    │   ├── scheduler(returnAtDeadlock=true)
    │   └── exit(0)
    │
    └── parent:
        ├── close(fds[1])
        └── continue execution

Memory Model

• Within a domain: single-threaded, no races possible. No mutexes needed. Channels are the synchronization primitive.
• Between domains: complete isolation. No shared pointers. Channel data is serialized over IPC.
• GC: Boehm conservative GC per domain. Each forked process has its own heap.

Build Tags

Moxie uses moxie and moxie.unicore build tags:

//go:build moxie.unicore    → cooperative single-core (always true)
//go:build moxie            → moxie compiler (always true)
//go:build gc.boehm         → Boehm GC (default on linux/darwin)
//go:build scheduler.tasks  → cooperative scheduler (always true)

Target Configuration

Moxie supports exactly 4 native targets plus JS:

GOOS/GOARCH	Scheduler	GC	Libc	Linker
linux/amd64	tasks	boehm	musl	ld.lld
linux/arm64	tasks	boehm	musl	ld.lld
darwin/amd64	tasks	boehm	darwin-libSystem	ld.lld
darwin/arm64	tasks	boehm	darwin-libSystem	ld.lld
js	tasks	—	—	—

No embedded targets. No WASI. No Windows.