LMCode Overview & Architecture
LMCode is the statically typed domain language written inside
_lmcode_ ... end _lmcode_ blocks in an LMScript file. One compiler (dsl.ts in
lmscript) typechecks the block against a host's dsl.schema: 2 contract and compiles it to
one portable binary bytecode format (DSLB v6), which seven independent runtime SDKs load, verify,
and execute with zero runtime type dispatch.
Why a Separate Compiled Inner Language?
Compile-Time Contract Guarantee
Every method call, function overload, context variable, enum constant, and SAM rule interface is resolved
at compile time against the host's dsl.schema: 2 JSON document. If a method name or argument type is wrong,
lmscript --check rejects the script (exit 2) before any process or cloud call runs.
Cryptographic Schema Binding
Every .dslb file starts with a 38-byte header containing magic "DSLB", version 6,
and the exact SHA-256 digest of the host's schema bytes. The host VM recomputes the hash on load and
refuses any mismatched bytecode with LOAD_SCHEMA_MISMATCH.
Bytecode & Stack Verifier Before Execution
Before executing a single instruction, Program::load verifies every opcode, constant index,
import signature, forward-only jump, paired FOR_RANGE / WHILE_BEGIN loop, and dataflow stack depth.
Structured Terminal Return Envelope
Hosts communicate results back to LMScript's run_lmcode(prog) through a strict single terminal
LMCODE_RETURN_BEGIN ... LMCODE_RETURN_END JSON envelope with typed result contracts and dry-run markers.
The lmctl-ai/lmcode* Repository Family
The LMCode ecosystem is organized across the specification hub, 7 runtime SDKs, and 8 canonical shop sample hosts:
| Repository | Language / Target | Role & Key Entry Points |
|---|---|---|
lmctl-ai/lmcode |
Spec & Guides | Authoritative language, grammar (EBNF + tree-sitter), dsl.schema: 2, DSLB v6, std, rest, and host protocol specifications. |
lmctl-ai/lmcode-cpp |
C++17 (Header-Only + C ABI) | Reference loader/verifier/VM (include/dslvm.hpp), lmcode_std_v3 owner (std/lmcode-std.schema.json), C ABI (liblmcode_c), and conformance suite. |
lmctl-ai/lmcode-rust |
Rust (Edition 2021) | Safe Rust crate (dslvm) with Registry, Program::load, Context, lmcode_std_v3, and rest module. |
lmctl-ai/lmcode-go |
Go 1.22+ | Zero-cgo Go package (github.com/lmctl-ai/lmcode-go) powering Go-based cloud and mock hosts. |
lmctl-ai/lmcode-java |
Java 21 (Maven) | JVM runtime SDK powering Java/Kotlin/Scala hosts and GraalVM native-image CLIs such as lmaws. |
lmctl-ai/lmcode-csharp |
C# / .NET 8 | Managed .NET 8 runtime SDK (Lmcode.DslVm) with full verifier, 206-sig stdlib, and rest module. |
lmctl-ai/lmcode-js |
JavaScript ESM (Node 20+) | Pure ESM runtime (src/vm.mjs, InvocationResults) with BigInt int64 wrapping and zero native addons. |
lmctl-ai/lmcode-python |
Python 3.10+ | Pure Python 3 bytecode loader, verifier, VM, and host registry for Python data/ML hosts. |
lmcode-{c,cpp,rust,go,csharp,java,kotlin,scala}-sample |
8 Sample Hosts | Canonical sample_shop_v1 reference hosts (Money, Shop, Ledger, Currency, Adjuster, Score) verified by the shared 56-case sample suite. |
End-to-End Example: Compiling & Running an LMCode Block
# 1. Inspect the host schema from LMScript if desired
s = load_schema(cli="lmaws" install="github:lmctl-ai/lmaws@v0.1.34");
println("Host schema loaded: " + type(s));
# 2. Author a statically typed _lmcode_ block
prog = _lmcode_ cli="lmaws" install="github:lmctl-ai/lmaws@v0.1.34";
let cloud = aws.demo();
let zones = cloud.zones();
lmcode_return_put("zone_list", json_parse(zones.json()));
end _lmcode_
# 3. Execute and read the structured LMCODE_RETURN envelope
r = run_lmcode(prog);
require(r.ok, "LMCode failed: " + r.get("message", "host execution failed"));
println("Result: " + json_stringify(r.result, 2));