ilo-lang · danieljohnmorris · May 19, 2026 · May 19, 2026 · May 19, 2026 · May 19, 2026
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -19,7 +19,7 @@ crate-type = ["staticlib", "rlib"]
 [features]
 default = ["cranelift", "http"]
 http = ["dep:minreq"]
-cranelift = ["dep:cranelift-codegen", "dep:cranelift-frontend", "dep:cranelift-jit", "dep:cranelift-module", "dep:cranelift-native", "dep:cranelift-object", "dep:target-lexicon"]
+cranelift = ["dep:cranelift-codegen", "dep:cranelift-frontend", "dep:cranelift-jit", "dep:cranelift-module", "dep:cranelift-native", "dep:cranelift-object", "dep:target-lexicon", "dep:postcard"]
 llvm = ["dep:inkwell"]
 tools = ["dep:tokio", "dep:reqwest"]
 
@@ -36,6 +36,7 @@ cranelift-module = { version = "0.116", optional = true }
 cranelift-native = { version = "0.116", optional = true }
 cranelift-object = { version = "0.116", optional = true }
 target-lexicon = { version = "0.12", optional = true }
+postcard = { version = "1.0", features = ["alloc"], default-features = false, optional = true }
 inkwell = { version = "0.5", features = ["llvm18-0"], optional = true }
 minreq = { version = "2.14", default-features = false, features = ["https-rustls"], optional = true }
 tokio = { version = "1", features = ["rt", "macros", "process", "io-util", "sync"], optional = true }

diff --git a/SPEC.md b/SPEC.md
@@ -129,7 +129,7 @@ Syntax: `(<param>:<type> ...><return-type>;<body>)`. Same shape as a top-level f
 f xs:L n thr:n>L n;flt (x:n>b;>x thr) xs   -- captures `thr`
 ```
 
-Phase 2 captures run natively on the tree interpreter, the register VM, and the Cranelift JIT - every in-process engine. Each free variable is snapshot by value at the call site (`Expr::MakeClosure`) and appended to the call frame's arg slice on dispatch. The AOT backend lags here: HOFs taking a function value (including capturing closures) currently miscompile and need a separate fix. The ctx-arg form (`srt fn ctx xs`) remains the cross-engine alternative when you want explicit state without forming a closure.
+Phase 2 captures run natively on every engine: the tree interpreter, the register VM, the Cranelift JIT, and the Cranelift AOT backend. Each free variable is snapshot by value at the call site (`Expr::MakeClosure`) and appended to the call frame's arg slice on dispatch. The AOT backend additionally embeds the postcard-serialised `CompiledProgram` into the binary's `.rodata` and publishes TLS pointers on startup, so dispatch helpers can re-enter the VM on user-fn callbacks. The ctx-arg form (`srt fn ctx xs`) remains the cross-engine alternative when you want explicit state without forming a closure.
 
 ---
 
@@ -1533,7 +1533,7 @@ ilo serv                          -- long-lived JSON request/response loop
 
 **AOT entry-pick.** `ilo compile file.ilo -o out` (alias `ilo build`) follows the same entry-pick rules as the in-process engines: a single user-defined function is used directly; on multi-function files the entry is `main` if defined, otherwise the explicit positional `func` arg (`ilo compile file.ilo -o out run`); otherwise the compile fails with `ILO-E801` and exits 1 without writing a binary. AOT does not fall back to "first declared function" - that historical default produced binaries that called the wrong entry symbol and SIGSEGV'd at runtime.
 
-**Default engine.** The bytecode register VM is the default execution path. It supports every opcode (closures with Phase 2 capture, listview windows, fused len-of-filter, every modern shape), and avoids the JIT compile-and-bail cost paid by the pre-v0.11.9 Cranelift-first default whenever a program touched an opcode the JIT couldn't handle. Cranelift JIT is opt-in via `--jit`; on opt-in, the JIT runs hot numeric loops and falls back to the VM on bailout. The tree interpreter (`--run-tree`) remains the canonical-semantics reference. Phase 2 captures run natively on tree, VM, and JIT - no engine fallback needed. For long-running workloads where the JIT pays for itself, opt in explicitly; for most agent workloads the VM is the right default.
+**Default engine.** The bytecode register VM is the default execution path. It supports every opcode (closures with Phase 2 capture, listview windows, fused len-of-filter, every modern shape), and avoids the JIT compile-and-bail cost paid by the pre-v0.11.9 Cranelift-first default whenever a program touched an opcode the JIT couldn't handle. Cranelift JIT is opt-in via `--jit`; on opt-in, the JIT runs hot numeric loops and falls back to the VM on bailout. The tree interpreter (`--run-tree`) remains the canonical-semantics reference. Phase 2 captures run natively on every engine - tree, VM, JIT, and AOT (`ilo compile`); AOT embeds the postcard `CompiledProgram` blob into the binary's `.rodata` so dispatch helpers can re-enter the VM on user-fn callbacks the same way the in-process runners do. For long-running workloads where the JIT pays for itself, opt in explicitly; for most agent workloads the VM is the right default.
 
 **Subcommand dispatch.** The first positional argument is interpreted as a function name when it has the shape of an ilo identifier - `[a-z][a-z0-9]*(-[a-z0-9]+)*` - so `ilo file.ilo list-orders` routes to the `list-orders` function. Args that don't match the ident shape (file paths like `/tmp/data.json`, numbers, sigils, bracketed lists, anything with a `.` or `/`) route to `main` (or the entry function) as a positional CLI arg instead. Trailing dashes (`foo-`), doubled dashes (`foo--bar`), and negative numbers (`-1`) are not idents and pass through as data.