Developer docs for main, checked against 9849aeb
on 2026-11-16.
Workflow runtime
VM and execution loop
src/topology.rs contains bytecode validation, VmState, invocation handling, deployment, and the execution loop. It is the central file for following a compiled workflow.
The VM records agents, instances, typed ports, connections, state, timers, and reactions. Execution advances through ordered tags: (timestamp, microstep). Timestamps use nanoseconds; microsteps order work at the same logical time.
Plain connections propagate within a tag. after 0 introduces a microstep; positive delays advance time. Timers enqueue future triggers. The runtime normally paces logical time against elapsed time; --fast removes that wait.
For a tag, the runtime propagates events and runs triggered reactions. Agent invocations must finish before the tag completes. Future delayed work goes onto the queue. The diagram observer receives execution updates.
Two reaction implementations
Agent tasks become prompts delivered through a backend. An invocation records trigger values, permitted effects, and team state. The agent buffers writes through MCP and completes the invocation; the runtime validates those writes before accepting them.
Native Rust bodies use src/reaction.rs. It generates a crate, builds an executable with Cargo, and invokes that executable with a line-based input/output protocol. Rust bodies are captured by the Lean compiler as source; Cargo compiles them.
Shared contexts are string state associated with selected agents. Their values and directives are included in task context, and completion requires an update or explicit preservation.
Control and observation
src/deploy.rs defines deployment lifecycle states and control operations. A pause takes effect at a tag boundary and produces a durable checkpoint. The runner exits; resume starts a new runner from that checkpoint.
src/diagram.rs defines snapshots, events, and the observer interface used by diagram clients. src/serve.rs maintains the externally visible run record and relays diagram requests.
For persistence, mutation, and the distinction between file snapshots and runtime checkpoints, continue to state and recovery.