spacydo

"I thought of objects being like biological cells and/or individual computers on a network, only able to communicate with messages." — Alan Kay

---

SPACYDO is a stack-based virtual machine with image-based persistence. The core abstraction is a TASK: a persistent entity carrying its own executable bytecode alongside its state. Tasks can observe and modify fields of other tasks and their own.

VM TYPES

All stack values are 64-bit (u64) Nan-Boxed values encoding 6 distinct types:

Type	Description
TRUE_VAL, FALSE_VAL	boolean true / false
U32	unsigned 32-bit integer
CallData	reference into InstructionsPool
String	[offset(25 bit) size(16 bit) tag(3 bits)] - fat pointer to a vector of u8 allocated to vm's linear memory
VecU32	[offset (25 bit) size (16 bit) tag (3 bits) - fat pointer to a vector of u32 allocated to vm's linear memory

See values.rs

VM INSTRUCTIONS (dot - textual representation of the spacydo binary format )

Type	Instructions
Stack Operations	PUSH_U32, PUSH_STRING, PUSH_CALLDATA, PUSH_STATE, PUSH_MAX_STATES, DUP, SWAP, DROP
Task Operations	T_CREATE, T_GET_FIELD, T_SET_FIELD, T_DELETE
Storage Operations	S_SAVE, S_LEN
Memory Operations	M_STI, M_ST, M_MUT
Control Flow	DO, LOOP, LOOP_INDEX, CALL, END_CALL, IF..THEN
Logic operations	EQ, NEQ, LT, GT
Arithmetic operations	MUL, MULI

Instruction set with description is here: opcodes.rs VM instruction set is intentionally minimal and aiming to remain minimal in a future. While bytecode instructions are expressive enough already, bytecode is verbose, so new instructions should be added.

What this enables

Because behavior lives inside the task rather than in application code, programs therefore consist of networks of interacting tasks whose behavior emerges from state transitions, and this behavior is updatable at runtime without application recompilation.

The same primitive naturally expresses:

Workflows — tasks that create, modify, chain, or destroy other tasks on state change. Behavior loaded from TOML at runtime, no recompilation required.

State machines — a task whose instructions encode its own transition rules. The traffic light example is a single task: instructions define red→green→yellow→red, no external FSM framework needed.

Circuitry simulation — the BCD decoder example implements a full Binary Coded Decimal decoder from Petzold's Code. Every NOT gate and AND gate is a persistent task with its own instructions that reads input task states and updates its own.

Examples

Example	What it demonstrates
examples/todo	Programmable tasks — chain, hide, self-destruct, conditional completion
examples/traffic_light	Finite State machine as a single self-transitioning task
examples/bcd-decoder	BCD decoder circuitry from "Code" by Charles Petzold book emulation with logic gates as Tasks

Various Usage examples:

let ops = "PUSH_U32 2 PUSH_U32 2 EQ IF PUSH_U32 3 THEN PUSH_U32 4 PUSH_STRING HELLO PUSH_U32 42 PUSH_U32 42 EQ PUSH_CALLDATA [ PUSH_U32 11 END_CALL ]";
let bytecode = VM::dot2bin(ops)?;
/* same without default features:
 let bytecode = vec![
        0x01, 0x00, 0x00, 0x00, 0x02, 0x01, 0x00, 0x00, 0x00, 0x02, 0x16, 0x1A, 0x00, 0x00, 0x00,
        0x15, 0x01, 0x00, 0x00, 0x00, 0x03, 0x01, 0x00, 0x00, 0x00, 0x04, 0x1B, 0x00, 0x05, 0x04,
        0x01, 0x48, 0x45, 0x4C, 0x4C, 0x4F, 0x01, 0x00, 0x00, 0x00, 0x2A, 0x01, 0x00, 0x00, 0x00,
        0x2A, 0x16, 0x04, 0x00, 0x06, 0x01, 0x00, 0x00, 0x00, 0x0B, 0x12,];
*/
// inits vm with instructions
let mut vm = VM::init(bytecode)?;

// executes instructions and returns raw stack with NaN-boxed values
let raw_stack = vm.run()?;


// unboxing raw values returns: 
// [U32(3), U32(4), String("HELLO"), Bool(true), CallData("PUSH_U32 11 END_CALL")]
let unboxed_stack = vm.unbox(&raw_stack).collect::<VMResult<Vec<_>>>()?;

// returns 3u32
let _val:u32 = unboxed_stack[0].as_u32()?;

// returns [1,0,0,0,11,18,] - Vec<u8>
let _calldata:&str = unboxed_stack[4].as_calldata()?;

// example with memory write
let ops_mem = "PUSH_U32 10 MULI 4 NEW_VEC_U32 PUSH_U32 10 PUSH_U32 0 DO LOOP_INDEX LOOP_INDEX M_MUTA LOOP";
let bytecode = VM::dot2bin(ops_mem).unwrap();
let mut vm = VM::init(bytecode).unwrap();
let raw_stack = vm.run().unwrap();

let _un = vm.unbox(&stack).next().unwrap().unwrap();
// get &[u32]
let vecu32 = _un.as_vec_u32().unwrap();

Current Scope / Known Issues:

• storage and VM are not thread-safe
• instruction set is not yet stabilized
• task model is not yet stabilized
• nested loops limited to 2 levels
• nested calls limited to 2 frames