How it works

From a typed goal
to a verifiable run.

Liria is a compiler boundary: intent → typed IR → primitives. Below is the whole path — what you author, what the compiler produces, what the daemon runs, and how a third party replays it. No implicit side effects exist anywhere along it.

Intent

A typed goal, not a prompt

You author a .liria IDL file: the agent’s state, its messages, its protocols. This is the structure — a small, typed surface optimized for both humans and LLM generation. It is restricted by design: there are no implicit side effects to describe.

agent.liria

A language-neutral intermediate representation

The compiler reduces intent to JSON IR artifacts — intent, plan, receipts (schema liria.ir.v0.1). The IR is the contract: it describes what the agent intends, the steps to get there, and the receipts each step produces. liria-cli ir validate and ir hash check and fingerprint it.

intent · plan · receipts

Compile

Rust logic → sandboxed WASM

liriac reads the .liria structure plus Rust logic and emits a .wasm module, alongside a layout.json the host uses for introspection. The logic is ordinary Rust; the compiler’s job is to wrap it in the runtime’s primitives, not to invent a new execution model.

agent.wasm · layout.json

Host

liriad runs it under policy

The daemon loads the WASM into a wasmtime instance, manages lifecycle, and enforces policy plus fuel budgets. Host functions for network, disk, and spawn are capability-scoped and gated by interceptors. The IPC surface is a token-gated Unix socket; Ping and Health stay token-exempt for liveness.

liriad

Replay

Every turn is a recorded, verifiable fact

Each turn writes a turn record: input, output, and a state hash. replay replay re-executes it; replay verify proves the second run is byte-identical to the first; replay diff reports MATCH or the first divergent turn. Determinism is the audit — you do not trust the run, you re-run it.

turn record (BLAKE3)

Why replay is the whole point.

You cannot make an LLM deterministic. You can make the platform around it deterministic and fully logged. Liria treats the model as an input source — its model id, parameters, prompt, and tool results are recorded — and then makes every decision the platform takes replayable around that recorded input.

# record a turn, then prove it replays byte-identical
liria-cli replay record  --agent-id onboarding-demo
liria-cli replay replay  --turn-id  $TURN_ID
liria-cli replay verify  --original $TURN_ID --replay $TURN_ID-replay
liria-cli replay diff    --original $TURN_ID --replay $TURN_ID-replay

# Replay completed deterministically
# Replay verified (hash: blake3:<hex>)
# Replay diff: MATCH

A MATCH is a claim a third party can re-derive without trusting you. A MISMATCH points at the first divergent turn, so the boundary of any non-determinism is locatable, not vague.

The four laws of the host.

The runtime is governed by four mechanical constraints. They are how the host holds many agents, observes them, tests them, and bounds their cost — without trusting the agent to behave.

Glass box

The host reads guest memory directly via layout.json — passive introspection at zero observability cost. You can see an agent’s state without instrumenting it.

Hyper-sleep

Idle agents serialize their state to disk (orthogonal persistence) and free their RAM. The host can hold far more agents than memory, waking them on demand.

Truman show

WASM I/O interfaces are virtualized. The same agent runs identically against production I/O or a simulated, deterministic world — the agent cannot tell which.

Energy physics

Gas metering at the instruction level. An agent runs against a fuel budget; when the wallet hits zero, execution traps. Runaway cost is structurally impossible.

Liria is the framework. Dragons is the runtime.

A framework is only useful against a host that runs exactly its primitives. Liria compiles intent to canonical IR and WASM; Dragons runs that IR, enforces policy and leases, captures receipts, and produces evidence packs you can export and replay.

The analogyFrameworkHost platform

Authoring Liria — author intent and agents, compile to IR + WASM, simulate and replay locally Dragons — multi-tenant control plane that runs the IR, enforces leases, captures receipts

Deploy unit A typed agent + its policy and IR schema version An always-on process plus job DAGs, with replay as a first-class feature

Audit Turn records prove local determinism Evidence packs replay goal → action → evidence → outcome

“Dragons is the platform for governed autonomous processes; Liria is the framework that targets it.”

See it produce a MATCH.

The quickstart walks the whole pipeline against the repo’s example IR.

Run the quickstart Security model