REFERENCE

Guest ABI overview

The fixed binary contract between WASM guests and the Samoza runtime — module index.

The Guest ABI is the binary interface between WASM guest programs and the Samoza runtime. It defines the host-imported WASM functions and guest-exported entry points that constitute the fixed contract.

This page is the module index. For the developer’s introduction see Develop · Guest ABI.

Architecture

┌──────────────────────────────────┐
│         Guest program            │  ← Your code (TinyGo → WASM)
│    on_init() / on_process()      │
├──────────────────────────────────┤
│         Guest Library            │  ← Convenience wrappers (optional)
├──────────────────────────────────┤
│         Guest ABI                │  ← This specification
├──────────────────────────────────┤
│         Samoza Runtime (zrun)    │  ← Host (Go + wazero)
└──────────────────────────────────┘

Modules

Core — universal

Module	Purpose
Lifecycle	`on_init`, `on_process`, `on_close`, memory model
System	`sys.log`, `sys.sleep`, `sys.yield`, `sys.self_emit`
Network	`net.emit_to`, `net.recv_next` — message passing between spaces
Capabilities	The capability model — declaration and enforcement

Extended — software services

Module	Purpose
Data	Key/value storage — `data.get`, `data.put`, `data.list`, `data.delete`
Agents	DF, AF, LLM agent invocation — `agent.invoke_df`, `agent.invoke_af`, `agent.invoke_llm`
Events	Computed events from recognizers — `events.register_recognizer`, `events.subscribe`
Intelligence Cache	LLM response caching, semantic lookup — `ic.lookup`, `ic.store`

Device — physical I/O

Module	Purpose
Sensors	Generic subscribe/read — `sensors.subscribe`, `sensors.read`
Actuators	Generic lock/command/release — `actuators.lock`, `actuators.command`, `actuators.release`
Audio	Microphone capture and speaker playback streaming

UI spaces are not in the Guest ABI — they run in the browser.

Conventions

Return code (int32): 0 = success, negative = error, positive = bytes/count.

Data: All host-guest data is JSON unless explicitly noted (audio is raw bytes).

Device knowledge: None. Sensor and actuator types are extensible strings; the ABI knows nothing about cameras, motors, or thermometers specifically. Domain knowledge lives in the Guest Library.

Import paths

github.com/anrl/samoza/components/zrun/guest/abi/
├── net          — Network messaging
├── data         — Key/value storage
├── node         — Node primitives
├── sys          — System functions
├── ic           — Intelligence cache
├── agent        — Agent invocation
├── mem          — Memory management
├── z            — Low-level primitives
└── sys/io       — Stream I/O (audio)

Compilation

Guests compile with TinyGo targeting WASI:

tinygo build -target wasi -scheduler=none -opt=z -o core.wasm .

Constraints: no fmt (binary bloat), use encoding/json for serialization, use strconv for number conversion, sys.Log() takes exactly one string argument, main() exists but is empty.

What the ABI doesn’t cover

The Guest ABI specifies only the WASM import/export surface. It does not cover:

Construction-time concerns (space creation, path wiring) — see the MEX format.
Domain-specific helpers (car control, vision typed structs) — those live in the Guest Library.
UI rendering — UI spaces are browser-side and have a separate JavaScript surface.

Per-module specifications for each ABI module are in the source repository at docs/reference/guest-abi/. They will be ported here progressively. The Lifecycle module is the first one available — it covers the entry points every WASM space must implement.