Developer docs for main, checked against 9849aeb
on 2026-11-16.
Compiler and bytecode
Source to runtime
The Lean compiler and Rust runtime meet at a JSON file:
.omar source + imported schemas
-> omarc
-> JSON bytecode
-> Rust VM validation
-> workflow execution
lang/Main.lean reads source and imported schemas and selects the compiler mode. lang/Omar/Compiler.lean contains tokenization, parsing, elaboration, and bytecode generation. lang/spec.md defines the language contract.
The CLI modes are:
omarc [--local-imports] input.omar output.json
omarc [--local-imports] --diff old.omar new.omar diff.json
omarc [--local-imports] --lean input.omar model.lean
omarc [--local-imports] --prove input.omar properties.json verdicts.json
--local-imports restricts imports to relative paths within the program’s directory. HTTP-submitted companion files need this boundary because the source arrives from a request.
Bytecode contract
Bytecode and Instruction are the Rust wire definitions. Bytecode carries version, team, and instructions. Instructions use an op discriminator with snake-case names; the VM accepts version 1.
Instructions describe declarations and connections: instances, agents, ports, imported types, state, parameters, timers, and reactions. They also include plan/control operations. Read the enum for the complete vocabulary rather than copying it into a second specification.
The runtime validates declarations, identifiers, references, types, and topology before execution. Compiler output is not a substitute for runtime validation.
.omar source remains canonical. Bytecode can be rebuilt; source is what recovery and live program changes preserve.
Models and proofs
Omar.Model renders a program model. Omar.Reactor supplies reactor semantics; Omar.Verify supplies verification support. Omar.Prove checks requested Lean properties against the model.
These properties concern the program model. Agent task results still cross the Rust invocation validation boundary at runtime. src/properties.rs connects property checks to the server.