Session D.5: extract CLI to omnimcode-cli, wire OMC_HBIT_JIT=1

Move src/main.rs out of omnimcode-core (where it couldn't depend
on omnimcode-codegen without a workspace cycle) into a new
omnimcode-cli package that depends on both. The shipped binary
name is preserved (omnimcode-standalone) so scripts that invoke
it keep working.

What `OMC_HBIT_JIT=1` does now (with `--features llvm-jit`):
- Compile the parsed program to bytecode
- JIT-lower every user fn in dual-band mode; silently skip ones
  the codegen can't yet handle (strings/dicts/cross-fn calls)
- Register a dispatch closure on the Interpreter that routes
  matching user-fn calls through the native fn pointer
- Run the program tree-walk-as-usual; the dispatch hook
  short-circuits to native for the JIT'd fns

Smoke test verifies: `OMC_HBIT_JIT=1 omnimcode-standalone f.omc`
correctly JITs `double`, `factorial` (recursive), `sum_to`
(while-loop with locals), and runs them at native speed (timing
in Session E).

Three release-build fixes were needed:
1. Workspace [profile.release] had `lto = "fat"` + `strip = true`.
   That combination causes LLVM JIT to segfault during
   JitContext::new because MCJIT does dlopen-style symbol lookup
   against the binary, and aggressive LTO + stripping scrubs
   those symbols. Changed to `lto = "off"`, `strip = "debuginfo"`,
   `codegen-units = 16`. Mild release-perf hit, JIT works.
2. jit_module was interleaving lower-then-extract per fn. That
   triggers JIT finalization on a partially-populated module and
   FunctionNotFound on the next recursive reference. Switched to
   two-phase: lower ALL eligible fns first, then extract fn
   pointers from the now-complete module.
3. extract_raw_fn_ptr failures inside jit_module no longer
   propagate via `?` (which aborted the whole JIT registry).
   Per-fn errors now skip that fn and continue; tree-walk
   handles the skipped fn.

Help text updated: `omc --help` now documents `OMC_HBIT_JIT=1`
and `OMC_HBIT_JIT_VERBOSE=1`.

Workspace state: 149 omnimcode-core unit tests pass, 19 codegen
tests pass, 18 OMC harmonic-lib tests pass, smoke test green
in both tree-walk and JIT modes with identical output.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: RandomCoder-lab

Cargo.lock

@@ -5,6 +5,7 @@ members = [
     "omnimcode-wasm",
     "omnimcode-lsp",
     "omnimcode-codegen",
+    "omnimcode-cli",
 ]
 # omnimcode-python kept around but excluded from the default workspace.
 # It was the "Python embeds OMC" wrapper (extension-module mode); now
@@ -21,12 +22,25 @@ edition = "2021"
 authors = ["The Architect <architect@sovereign-lattice.io>"]
 license = "MIT"
 
-# Shared profile settings for all workspace members
+# Shared profile settings for all workspace members.
+#
+# LTO is OFF because the LLVM JIT runtime (omnimcode-codegen +
+# inkwell) does dlopen-style symbol resolution against the binary's
+# symbol table at runtime; `lto = "fat"` inlines/mangles those
+# symbols and causes a segfault during JitContext::new. The cost
+# of disabling LTO is mild (a few % slower release binary) and is
+# acceptable in exchange for the JIT working in shipped binaries.
+# Per-package `lto` overrides aren't supported by cargo, so this
+# is a workspace-wide setting.
+#
+# `strip = "debuginfo"` keeps the symbol table (which LLVM JIT
+# needs) but discards debug info (which it doesn't). Binary size
+# stays in the same ballpark as `strip = true`.
 [profile.release]
 opt-level = 3
-lto = "fat"
-codegen-units = 1
-strip = true
+lto = "off"
+codegen-units = 16
+strip = "debuginfo"
 
 [profile.dev]
 opt-level = 1

Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "omnimcode-cli"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+license.workspace = true
+description = "OMNIcode standalone CLI — links the tree-walk interpreter, bytecode VM, optional Python embedding, and (under llvm-jit) the LLVM-backed dual-band JIT into one binary."
+
+# Preserve the historical binary name so scripts that invoke
+# `omnimcode-standalone` keep working after the Session D.5 split.
+[[bin]]
+name = "omnimcode-standalone"
+path = "src/main.rs"
+
+[features]
+default = ["python-embed"]
+# CPython embedding for `py_*` builtins. Forwards to core.
+python-embed = ["omnimcode-core/python-embed"]
+# LLVM-backed dual-band JIT. When set at compile time, the CLI
+# consults `OMC_HBIT_JIT=1` at runtime; if also set, eligible user
+# fns are routed through omnimcode-codegen instead of tree-walk/VM.
+llvm-jit = ["dep:omnimcode-codegen", "dep:inkwell"]
+
+[dependencies]
+omnimcode-core = { path = "../omnimcode-core", default-features = false }
+omnimcode-codegen = { path = "../omnimcode-codegen", optional = true, features = ["llvm-jit"] }
+# inkwell is needed at the CLI level only because we leak the LLVM
+# Context for process-lifetime; the dispatch closure lives on the
+# Interpreter and references the engine memory.
+inkwell = { version = "0.5", features = ["llvm18-0"], optional = true }

omnimcode-cli/Cargo.toml

@@ -97,6 +97,100 @@ fn maybe_register_python(interp: &mut Interpreter) {
 #[cfg(not(feature = "python-embed"))]
 fn maybe_register_python(_interp: &mut Interpreter) {}
 
+/// Wire the LLVM-backed dual-band JIT into the Interpreter when
+/// `OMC_HBIT_JIT=1` is set in the environment. Compiles the program
+/// to bytecode, attempts to JIT every user fn in dual-band mode, and
+/// installs a dispatch hook that routes future calls to the native
+/// code path.
+///
+/// The JIT context (LLVM Context + ExecutionEngine + native code
+/// pages) is `Box::leak`-ed because the compiled fn pointers must
+/// outlive the dispatch closure stored on the Interpreter, which in
+/// turn must live for the whole program. CLI tool process-lifetime
+/// is the right scope for this leak.
+///
+/// Functions whose bodies use ops the codegen layer doesn't yet
+/// support (strings, dicts, builtins, cross-fn calls) are silently
+/// skipped — they keep running through the tree-walk interpreter.
+#[cfg(feature = "llvm-jit")]
+fn maybe_register_jit(
+    interp: &mut Interpreter,
+    statements: &[omnimcode_core::ast::Statement],
+) {
+    if std::env::var("OMC_HBIT_JIT").as_deref() != Ok("1") {
+        return;
+    }
+    let module = match omnimcode_core::compiler::compile_program(statements) {
+        Ok(m) => m,
+        Err(e) => {
+            eprintln!("[OMC_HBIT_JIT] compile_program failed: {} — falling back to tree-walk", e);
+            return;
+        }
+    };
+    // Leak the LLVM Context to give it a 'static lifetime. Required
+    // because JitContext borrows from Context, and the dispatch
+    // closure holds raw fn pointers into the JitContext's
+    // ExecutionEngine. CLI process-lifetime is the right scope.
+    let context: &'static inkwell::context::Context =
+        Box::leak(Box::new(inkwell::context::Context::create()));
+    let jit = match omnimcode_codegen::JitContext::new(context) {
+        Ok(j) => j,
+        Err(e) => {
+            eprintln!("[OMC_HBIT_JIT] JitContext::new failed: {} — falling back", e);
+            return;
+        }
+    };
+    let jitted = match jit.jit_module(&module) {
+        Ok(map) => map,
+        Err(e) => {
+            eprintln!("[OMC_HBIT_JIT] jit_module failed: {} — falling back", e);
+            return;
+        }
+    };
+    let n_jitted = jitted.len();
+    let n_total = module.functions.len();
+    if std::env::var("OMC_HBIT_JIT_VERBOSE").as_deref() == Ok("1") {
+        eprintln!(
+            "[OMC_HBIT_JIT] JIT'd {}/{} user fns to dual-band native code",
+            n_jitted, n_total
+        );
+        for name in jitted.keys() {
+            eprintln!("  - {}", name);
+        }
+    }
+    // Leak the JitContext too — the dispatch closure references its
+    // engine memory.
+    let jit_static: &'static omnimcode_codegen::JitContext<'static> = Box::leak(Box::new(jit));
+    let _ = jit_static; // currently unused; kept for documentation
+    let dispatch: omnimcode_core::interpreter::JitDispatch = std::rc::Rc::new(
+        move |name: &str, args: &[omnimcode_core::value::Value]| {
+            use omnimcode_core::value::{HInt, Value};
+            let jf = jitted.get(name)?;
+            if args.len() != jf.arity {
+                return None;
+            }
+            let mut int_args: Vec<i64> = Vec::with_capacity(args.len());
+            for a in args {
+                match a {
+                    Value::HInt(h) => int_args.push(h.value),
+                    Value::Bool(b) => int_args.push(if *b { 1 } else { 0 }),
+                    _ => return None, // non-int arg → fall through to tree-walk
+                }
+            }
+            jf.call(&int_args)
+                .map(|r| Ok(Value::HInt(HInt::new(r))))
+        },
+    );
+    interp.set_jit_dispatch(Some(dispatch));
+}
+
+#[cfg(not(feature = "llvm-jit"))]
+fn maybe_register_jit(
+    _interp: &mut Interpreter,
+    _statements: &[omnimcode_core::ast::Statement],
+) {
+}
+
 /// `--install [SPEC]`. SPEC can be:
 ///
 ///   * a URL                 → fetch and store under that basename
@@ -504,6 +598,9 @@ fn print_help() {
     println!("  OMC_OPT_STATS=1        print optimizer pass statistics");
     println!("  OMC_STDLIB_PATH=...    colon-separated module search path");
     println!("  OMC_NO_PYTHON=1        skip embedded CPython initialisation");
+    println!("  OMC_HBIT_JIT=1         JIT eligible user fns through omnimcode-codegen");
+    println!("                         (dual-band <2 x i64> SSE2; LLVM-backed)");
+    println!("  OMC_HBIT_JIT_VERBOSE=1 print which fns got JIT'd at startup");
 }
 
 fn read_and_run(path: &str) -> Result<(), String> {
@@ -649,6 +746,7 @@ fn execute_program(source: &str) -> Result<(), String> {
 
     let mut interpreter = Interpreter::new();
     maybe_register_python(&mut interpreter);
+    maybe_register_jit(&mut interpreter, &statements);
     // OMC_HEAL_RETRY=1 — catch runtime errors after execution starts,
     // run the heal pass on a fresh copy of the AST, and retry. Captures
     // bugs that the static heal pass missed (e.g. dynamic /0, missing

omnimcode-core/src/main.rs omnimcode-cli/src/main.rsomnimcode-core/src/main.rs renamed to omnimcode-cli/src/main.rs

@@ -194,21 +194,18 @@ impl<'ctx> JitContext<'ctx> {
         &self,
         module: &omnimcode_core::bytecode::Module,
     ) -> Result<HashMap<String, JittedFn>, CodegenError> {
-        let mut out: HashMap<String, JittedFn> = HashMap::new();
+        // Two-phase: lower ALL eligible fns into the LLVM module
+        // first, THEN extract fn pointers. Interleaving the phases
+        // makes get_function trigger JIT finalization on a partially-
+        // populated module, which can refuse to resolve recursive or
+        // cross-fn references that point to fns we haven't lowered
+        // yet (FunctionNotFound).
+        let mut to_extract: Vec<(String, String, usize)> = Vec::new(); // (orig, suffixed, arity)
         for (name, cf) in &module.functions {
             let suffixed = format!("{}_hbit", name);
             match self.lower_function_dual_band(cf) {
                 Ok(_) => {
-                    // get_function::<F> triggers JIT finalization and
-                    // returns a JitFunction wrapping the raw pointer.
-                    // We dispatch on arity to pick the right F so we
-                    // can extract the raw fn pointer for storage.
-                    let arity = cf.params.len();
-                    let fn_ptr = unsafe { self.extract_raw_fn_ptr(&suffixed, arity)? };
-                    out.insert(
-                        name.clone(),
-                        JittedFn { arity, fn_ptr },
-                    );
+                    to_extract.push((name.clone(), suffixed, cf.params.len()));
                 }
                 Err(_) => {
                     // Lowering failed mid-emission. The LLVM module
@@ -222,6 +219,18 @@ impl<'ctx> JitContext<'ctx> {
                 }
             }
         }
+        let mut out: HashMap<String, JittedFn> = HashMap::new();
+        for (name, suffixed, arity) in to_extract {
+            match unsafe { self.extract_raw_fn_ptr(&suffixed, arity) } {
+                Ok(fn_ptr) => {
+                    out.insert(name, JittedFn { arity, fn_ptr });
+                }
+                Err(_) => {
+                    // Extraction failure → skip this fn, keep going.
+                    // Tree-walk will handle it.
+                }
+            }
+        }
         Ok(out)
     }
 

omnimcode-codegen/src/lib.rs

@@ -9,10 +9,6 @@ documentation = "https://docs.rs/omnimcode-core"
 repository = "https://github.com/sovereignlattice/omnimcode"
 readme = "README.md"
 
-[[bin]]
-name = "omnimcode-standalone"
-path = "src/main.rs"
-
 [lib]
 path = "src/lib.rs"