Runtime Model

Turn execution is a process running. The configuration is the full state of that process at any point: its environment, managed context, memory, mailbox, tool registry, turn state, and remaining program.

Configuration (Process State)

Component	Type	Lifetime
env	Map: identifier → value	Lexical: push/pop on blocks
context	Tripartite structured context (P0: system/primacy, P1: working/recency, P2: episodic/middle)	Per process. Token-bounded
memory	Isolated O(1) key-value store (`HashMap`)	Per process. Persisted across runs
mailbox	Message queue (`send`/`receive`)	Per process
tool_registry	Map: tool name → handler	Set at startup
turn_state	Turn ID + pending suspension	Updated on turn entry / suspension
program	Remaining AST/bytecode	Current instruction pointer

notation

Config = (env, context, memory, mailbox, tool_registry, turn_state, program)

Serializable state = (env, context, memory, mailbox, turn_state)
Tool registry and program are provided separately on resume.

Invariants

Invariant— Token Budget (Gas)

context.append(expr) is gas-metered. If appending exceeds the budget, the VM executes the Entropic Expansion Policy: semantic summarization or Priority Stack eviction. The VM does not allow context to silently overflow.

Invariant— Priority Stack Preservation

P0 (system prompt) is never evicted. When P1 (working/recency) overflows, oldest items are evicted to P2. P2 (episodic/middle) oldest items are dropped first.

Invariant— Configuration Well-Formedness

All components are finite, valid structures at all times. No component is undefined or malformed.

Invariant— Serializable State

The tuple (env, context, memory, mailbox, turn_state) is sufficient to restore execution given the program and tool registry.

Transition: One Step

Small-Step Transition

Config → Config' or Config → Suspension(effect, arg, continuation). One step takes the configuration to a new configuration or to a suspension point.

Key transition rules:

let id = expr: evaluate expr and extend env with the binding
context.append(expr): evaluate the expression and append it to context (with token budget check)
remember(k, v): update memory with the given key and value
call(tool, arg): Suspension: the runtime executes the tool and resumes with its result
infer Type { prompt }: Suspension: an LLM call with schema validation
suspend: Suspension: writes a durable checkpoint to disk
use "path.wasm": Suspension: loads a Wasm module into its sandbox and returns closures
use schema::openapi("url"): Compile-time: the compiler fetches and expands the schema into native Turn closures before execution begins
return expr: the turn completes with the given value

Deterministic Semantics

IMPORTANT

Turn's core language is deterministic: given a configuration and input sequence, execution is reproducible. Non-determinism is quarantined at effect boundaries (call, infer). Same inputs produce the same state transitions.

This enables:

Debugging: Replay the input sequence to reproduce any fault.
State Inspection: suspend checkpoints the full VM state to disk. Load any past checkpoint to inspect exactly what the agent knew at that point.
Audit: Log inputs and reconstruct exactly what happened.
Testing: Inject deterministic mock responses via the TURN_LLM_PROVIDER=mock environment variable.

The Universal Loop

implementation pattern

1. Load:   Initialize VM with Program + State (or fresh)
2. Run:    Execute until Complete or Suspended
3. Handle: If Suspended(tool, arg, continuation):
 a. Persist continuation to durable storage
 b. Execute the tool (async, human-in-the-loop, etc.)
 c. Resume: load continuation, inject result, goto 2
4. Complete: Return final value

THE ENGINEERING SOLUTION