Session E: bench harness + measured 200-260x JIT speedup

Adds an `omc-bench` binary to omnimcode-cli that times the same
OMC fn through both tree-walk and the dual-band JIT, reports
min/median/mean per-call ns, and prints the speedup ratio.

The first run (documented in docs/jit_benchmark.md):

  factorial(12) x 200_000 iters:
    tree-walk  median 13,810 ns/call
    JIT        median     52.6 ns/call
    → 262.3x faster

  sum_to(100) x 200_000 iters:
    tree-walk  median 53,643 ns/call
    JIT        median    260 ns/call
    → 206.4x faster

This is the first concrete number for the SL HBit architecture's
"@hbit cuts times/cost" claim. We're at 262x from the @hbit
equivalent alone (Session D wiring + dual-band lowerer). The SL
demos claimed up to 80,000x with the full pragma stack (@hbit +
@Harmony + @predict + @avx512 + @unsafe); we still need the
divergent-band semantics (Session F), harmony-gated branch
elision (Session G), AVX-512 widening (Session H+), and array
support before that ceiling is reachable.

Honest caveats documented in docs/jit_benchmark.md:
- Microbenchmark — function-entry cost dominates, not throughput
- Bytecode VM not yet measured (calling convention is module-
  level; needs a Vm-internal looped harness)
- Whole-program speedup is bounded by Amdahl; real programs
  spend variable fractions inside JIT-eligible fns

What works today end-to-end on the CLI:
- Parse OMC source → compile bytecode → JIT every eligible fn
  through omnimcode-codegen's dual-band lowerer → register
  dispatch hook on Interpreter → run program with fns calling
  through native code

What's deferred:
- Session F: divergent α/β (phi-shadow on β at controlled
  points so harmony is a non-trivial signal)
- Session G: harmony-gated work elision in native code
- Session H: AVX-512 `<8 x i64>` widening + array support
- Cross-fn calls in dual-band lowerer (currently only recursive
  self-calls). Trivial extension but not in critical path
  because most hot fns are self-contained.

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

Author: RandomCoder-lab

docs/jit_benchmark.md

@@ -0,0 +1,94 @@
+# OMC dual-band JIT — first benchmark results
+
+**TL;DR:** 200–260× faster than tree-walk on pure-int hot loops. Microbenchmark caveats apply, but the architectural payoff that justified Sessions A–E is real.
+
+## Setup
+
+Run via the `omc-bench` binary added in Session E:
+
+```
+PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 ./target/release/omc-bench
+```
+
+The bench source is hardcoded into the binary so we measure the same program every time. It defines two self-contained ints-only functions — both JIT-eligible under the dual-band lowerer (Session C) and routed through the omnimcode-codegen pipeline:
+
+```omc
+fn factorial(n) {
+    if n <= 1 { return 1; }
+    return n * factorial(n - 1);
+}
+fn sum_to(n) {
+    h s = 0;
+    h k = 1;
+    while k <= n {
+        s = s + k;
+        k = k + 1;
+    }
+    return s;
+}
+```
+
+Each function is called 200,000 times in a tight loop. Wall-clock per call is reported as min / median / mean across 100 chunks.
+
+## Results (2026-05-15)
+
+```
+--- factorial(12) x 200000 iters ---
+  tree-walk  min= 13378.9ns  median= 13810.5ns  mean= 13835.5ns
+  JIT        min=    52.0ns  median=    52.6ns  mean=    53.0ns
+  → JIT vs tree-walk: 262.3x faster (median)
+
+--- sum_to(100) x 200000 iters ---
+  tree-walk  min= 52670.2ns  median= 53643.3ns  mean= 53728.6ns
+  JIT        min=   255.6ns  median=   260.0ns  mean=   260.5ns
+  → JIT vs tree-walk: 206.4x faster (median)
+```
+
+| Function | Tree-walk (median) | Dual-band JIT (median) | Speedup |
+|---|--:|--:|--:|
+| `factorial(12)` — 12 recursive calls + multiplies | 13,810 ns | 52.6 ns | **262×** |
+| `sum_to(100)` — 100-iter while loop with locals | 53,643 ns | 260 ns | **206×** |
+
+## How honest is this comparison?
+
+The numbers are credible as a measure of per-function-entry cost, but you should not extrapolate them to whole-program speedups. A few specific caveats:
+
+- **Microbenchmark by design.** The bench loop calls into OMC, immediately returns, and repeats. Real programs spend variable fractions of their time inside JIT-eligible fns vs. inside tree-walk-only paths (Python embed, strings, dicts, arrays, the OMC stdlib). For programs where the hot fn IS the bottleneck, the speedup approaches the numbers above. For programs where the hot fn is one piece of many, the realized speedup will be much smaller — capped by Amdahl.
+- **Calling convention overhead is included.** Tree-walk's `call_function_with_values` does a lot per call: scope push, synthetic Variable expression construction, dispatch-hook check, return-value unwind. JIT's call path is a single raw fn pointer invocation. Both costs are real, but in a deployed program the tree-walk path might already be amortized over many statements within the fn body, narrowing the gap.
+- **Bytecode VM not measured.** The VM's calling convention runs whole modules; extracting a fair per-call timing requires either a Vm-internal looped harness or refactoring the VM dispatch. Adding that to the bench is a small follow-up.
+- **No `@hbit`-only opt-in yet.** Session D auto-JITs every JIT-eligible user fn. A fn that would JIT but whose body the developer doesn't WANT JIT'd (e.g. for debugging) currently has no opt-out. This is a different problem from cost-cut, but worth flagging.
+
+## What this tells us about the SL HBit architecture
+
+The Sovereign Lattice `hbit_full_demo.omc` claimed:
+
+| Pragma stack | Claimed speedup |
+|---|---|
+| `@hbit` (dual-band) | 2× (parallel α/β computation) |
+| `+ @harmony` | 10× (eliminates error-checking overhead) |
+| `+ @predict` | 100× (no exception handling) |
+| `+ @avx512` | 16× (SIMD vectorization) |
+| `+ @unsafe` | 5× (fast-math, unroll) |
+| **Total** | **80,000×** |
+
+We're at 262× from `@hbit`-equivalent alone (Session D wiring). The dual-band representation is doing some of the work, but most of the speedup is "tree-walk → native" rather than "scalar → dual-band". To get the rest of the SL stack:
+
+- `@harmony` would need explicit α–β divergence (Session F+) and a substrate-routed harmony check fused into the hot path.
+- `@predict` would need the runtime to skip work when harmony stays high — that's the "low-harmony branches skipped" mechanism the user originally asked for, now realized as native code instead of tree-walk introspection.
+- `@avx512` widens `<2 x i64>` to `<8 x i64>` and demands array-processing OMC fns to actually have useful work for 8 lanes.
+
+## Reproduction
+
+```bash
+PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 LLVM_SYS_180_PREFIX=/usr/lib/llvm-18 \
+    cargo build --release --bin omc-bench --features llvm-jit
+
+PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 ./target/release/omc-bench
+# Optional: omc-bench <iters> <fn_arg>
+```
+
+Build dependencies (system, not Cargo): `llvm-18-dev`, `libpolly-18-dev`, `libzstd-dev`.
+
+## Numbers are timestamped
+
+These numbers were taken on 2026-05-15 with: AMD64 host, Rust release profile (`opt-level = 3`, `lto = "off"` — see Session D.5 for why LTO had to be disabled), LLVM 18.1.8 via inkwell 0.5. Reruns on different hardware or after compiler upgrades will produce different absolute timings, but the *ratio* should hold within ~30%.

omnimcode-cli/Cargo.toml

@@ -12,6 +12,15 @@ description = "OMNIcode standalone CLI — links the tree-walk interpreter, byte
 name = "omnimcode-standalone"
 path = "src/main.rs"
 
+# Session E bench harness — compares tree-walk, bytecode VM, and
+# dual-band JIT execution times for a hot OMC fn. Only meaningful
+# with `--features llvm-jit` (otherwise JIT mode short-circuits to
+# tree-walk).
+[[bin]]
+name = "omc-bench"
+path = "src/bench.rs"
+required-features = ["llvm-jit"]
+
 [features]
 default = ["python-embed"]
 # CPython embedding for `py_*` builtins. Forwards to core.

omnimcode-cli/src/bench.rs

@@ -0,0 +1,155 @@
+//! Session E benchmark harness.
+//!
+//! Measures wall-clock time for the same OMC user function under three
+//! execution modes:
+//!
+//!   1. Tree-walk (Interpreter::call_function_with_values)
+//!   2. Bytecode VM (Vm::run_module after rebinding the program to call
+//!      the target fn once per outer iteration)
+//!   3. Dual-band JIT (omnimcode-codegen JIT'd fn pointer, called
+//!      directly without going through the Interpreter)
+//!
+//! Reports min, median, mean per-call ns for each mode, plus speedup
+//! ratios relative to tree-walk.
+//!
+//! Usage:
+//!   omc-bench [iters] [fn-arg]
+//!
+//! Defaults: 200_000 iters, fn-arg = 12.
+//!
+//! The benchmark target is a hard-coded OMC source that defines
+//! `factorial(n)` plus `sum_to(n)` (two self-contained ints-only fns).
+//! Both are JIT-eligible; both are easy enough that the per-call cost
+//! is dominated by interpreter overhead rather than the computation
+//! itself — which is exactly the regime where the JIT win is sharpest.
+//!
+//! This is a *microbenchmark*. It deliberately compares overhead per
+//! function-entry, not throughput per CPU-cycle of useful work. Don't
+//! extrapolate the speedup ratios to whole-program speedups — those
+//! depend on how much time real programs spend inside JIT-eligible
+//! call frames vs. tree-walk-only paths (Python embed, builtins,
+//! string ops, etc.).
+
+use std::time::Instant;
+
+use inkwell::context::Context;
+use omnimcode_codegen::JitContext;
+use omnimcode_core::interpreter::Interpreter;
+use omnimcode_core::parser::Parser;
+use omnimcode_core::value::{HInt, Value};
+
+const SOURCE: &str = r#"
+fn factorial(n) {
+    if n <= 1 { return 1; }
+    return n * factorial(n - 1);
+}
+fn sum_to(n) {
+    h s = 0;
+    h k = 1;
+    while k <= n {
+        s = s + k;
+        k = k + 1;
+    }
+    return s;
+}
+"#;
+
+fn main() {
+    let args: Vec<String> = std::env::args().collect();
+    let iters: usize = args
+        .get(1)
+        .and_then(|s| s.parse().ok())
+        .unwrap_or(200_000);
+    let fn_arg: i64 = args.get(2).and_then(|s| s.parse().ok()).unwrap_or(12);
+
+    println!("=== omc-bench: tree-walk vs bytecode VM vs dual-band JIT ===");
+    println!("iters={}, fn_arg={}", iters, fn_arg);
+    println!();
+
+    bench_fn("factorial", iters, fn_arg);
+    println!();
+    bench_fn("sum_to", iters, 100);
+
+    println!();
+    println!("Notes:");
+    println!("  - 'tree-walk' goes through Interpreter::call_function_with_values");
+    println!("    (the path used by py_callback and other host->OMC dispatch).");
+    println!("  - 'JIT' calls the dual-band native fn directly via raw fn pointer");
+    println!("    (no Interpreter on the call path).");
+    println!("  - 'bytecode VM' is currently skipped — its calling convention");
+    println!("    doesn't expose a clean per-call-from-Rust entry; programs go");
+    println!("    through the full module run. A future bench will add a");
+    println!("    Vm-internal looped harness for a fair comparison.");
+}
+
+fn bench_fn(fn_name: &str, iters: usize, arg: i64) {
+    println!("--- {}({}) x {} iters ---", fn_name, arg, iters);
+
+    let mut parser = Parser::new(SOURCE);
+    let statements = parser.parse().expect("parse");
+
+    // Tree-walk timing.
+    let mut tw_interp = Interpreter::new();
+    tw_interp.execute(statements.clone()).expect("tw exec");
+    let (tw_min_ns, tw_med_ns, tw_mean_ns) = time_loop(iters, || {
+        let _ = tw_interp
+            .call_function_with_values(fn_name, &[Value::HInt(HInt::new(arg))])
+            .expect("tw call");
+    });
+    println!(
+        "  tree-walk  min={:>8.1}ns  median={:>8.1}ns  mean={:>8.1}ns",
+        tw_min_ns, tw_med_ns, tw_mean_ns
+    );
+
+    // JIT timing.
+    let module = omnimcode_core::compiler::compile_program(&statements).expect("compile");
+    let context = Context::create();
+    let jit = JitContext::new(&context).expect("jit");
+    let jitted = jit.jit_module(&module).expect("jit_module");
+    let jf = jitted
+        .get(fn_name)
+        .expect("expected fn to be JIT-eligible in Session E source");
+    let (jit_min_ns, jit_med_ns, jit_mean_ns) = time_loop(iters, || {
+        let _ = jf.call(&[arg]).expect("jit call");
+    });
+    println!(
+        "  JIT        min={:>8.1}ns  median={:>8.1}ns  mean={:>8.1}ns",
+        jit_min_ns, jit_med_ns, jit_mean_ns
+    );
+
+    if jit_med_ns > 0.0 {
+        let speedup = tw_med_ns / jit_med_ns;
+        println!(
+            "  → JIT vs tree-walk: {:.1}x faster (median)",
+            speedup
+        );
+    }
+}
+
+/// Time `f` `iters` times. Returns (min ns/call, median ns/call, mean
+/// ns/call). Uses one outer Instant::now() to amortize syscall
+/// overhead; per-call ns is total_ns / iters for min, but for median
+/// we sample chunks of ~iters/100 calls and pick the median chunk's
+/// per-call rate.
+fn time_loop<F: FnMut()>(iters: usize, mut f: F) -> (f64, f64, f64) {
+    let chunk_count = 100;
+    let chunk_size = iters / chunk_count;
+    let chunk_size = chunk_size.max(1);
+    let actual_iters = chunk_size * chunk_count;
+    let mut per_chunk_ns: Vec<f64> = Vec::with_capacity(chunk_count);
+    let outer_start = Instant::now();
+    for _ in 0..chunk_count {
+        let start = Instant::now();
+        for _ in 0..chunk_size {
+            f();
+        }
+        let dt = start.elapsed().as_nanos() as f64;
+        per_chunk_ns.push(dt / chunk_size as f64);
+    }
+    let total_ns = outer_start.elapsed().as_nanos() as f64;
+    per_chunk_ns.sort_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));
+    let min = per_chunk_ns[0];
+    let median = per_chunk_ns[chunk_count / 2];
+    let mean = total_ns / actual_iters as f64;
+    (min, median, mean)
+}