Mutable closures + module aliasing + benchmark suite

Track 1 — Mutable closures via Rc<RefCell> capture:

  Closure capture went from snapshot-by-value to shared-reference.
  Bank-account pattern works: multiple closures created in the
  same scope share the same captured bindings; mutations propagate.

    fn make_account(balance) {
        h deposit = fn(amount) { balance = balance + amount; ... };
        h withdraw = fn(amount) { balance = balance - amount; ... };
        ...
    }
    # deposit(50) then withdraw(30) → balance = 120, both see it

  Architecture changes:
    Value::Function.captured: HashMap → Rc<RefCell<HashMap>>
    Interpreter.locals: Vec<HashMap> → Vec<Rc<RefCell<HashMap>>>
    Lambda eval clones the current scope's Rc (siblings share)
    New assign_var method walks outward looking for existing binding
    Statement::Assignment now uses assign_var (not set_var)
    call_first_class_function pushes captured env Rc as a scope frame
    9 locals-access sites refactored to use the new Rc semantics

  Counter pattern: works (3 → 4 with second closure independent).
  Bank account pattern: works (100 → 150 → 120 → 120 across siblings).
  Test runner still passes 5/6 (1 intentional failure unchanged).

Track 2 — Module aliasing (import "path" as alias):

  The optional `as` clause was previously parsed but ignored.
  Now wired through: aliased imports register their functions as
  literal "alias.fname" keys in the function table.

    import "examples/math_module.omc" as math;
    println(arr_join(math.fib_up_to(100), ", "));

  Module resolver gained literal-path support — absolute paths,
  ./relative paths, and .omc-suffixed names now resolve directly
  without OMC_STDLIB_PATH. Short names still go through search
  paths for stdlib imports.

  Fixed an infinite-recursion bug while wiring this: call_function
  now checks self.functions for the exact name BEFORE splitting at
  `.`, so `call_function("math.fib") → call_module_function("math",
  "fib") → call_function("math.fib")` doesn't loop.

  Two example files:
    examples/math_module.omc  — reusable utility module
    examples/module_demo.omc  — usage demo

Track 3 — Benchmark suite (examples/benchmarks.omc):

  OMC's first proper benchmark suite. Times int arithmetic,
  string ops, array ops, harmonic primitives, and recursive fib
  with now_ms() and reports per-op nanoseconds.

  Tree-walk numbers (200K int_adds in 89ms = 445 ns/op,
  recursive fib(22) in 53ms = 2.4ms/op).

  Honest finding: OMC_VM=1 produces nearly-identical numbers on
  this suite because benchmarks dispatch user fns via call(fn,
  args), which routes through invoke_user_function (tree-walk).
  The VM advantage applies to direct Op::Call paths, not
  reflective dispatch. Useful signal for future VM work.

VM gains first-class-function-value fallback:

  Op::LoadVar now falls back to checking module.functions and the
  interpreter's function table when a name isn't a variable, so
  arr_map(xs, bench_int_add) works under OMC_VM=1.

  main.rs pre-registers user fn definitions into the VM's internal
  interpreter (vm.interp_mut().register_user_functions(&statements))
  before vm.run_module(...) so reflective dispatch resolves them.

Documentation:
  STDLIB.md — closures section rewritten for mutable semantics;
              counter and bank-account examples; VM caveat noted.
  README — "What's proven right now" gains four rows (mutable
           closures, modules, benchmark suite, plus the test runner
           that was already there).
  CHANGELOG — full track-by-track entry.

Regression: V.9b ✓✓✓ unchanged. H.5: 6/6 converge.
safe_keyword_host on both interpretation paths identical.

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

Author: RandomCoder-lab

CHANGELOG.md

@@ -4,6 +4,97 @@ All notable changes to OMNIcode will be documented in this file.
 
 ## [Unreleased]
 
+### Added (Mutable closures + module aliasing + benchmark suite, 2026-05-14)
+
+🎯 **Three more architectural moves: closures gain shared mutable state, the module system gets namespaced imports, and OMC has its first benchmark suite.**
+
+#### Track 1 — Mutable closures (Rc<RefCell> capture)
+
+The closure model went from snapshot-by-value to shared-reference. The bank-account pattern now works correctly:
+
+```omc
+fn make_account(balance) {
+    h deposit  = fn(amount) { balance = balance + amount; return balance; };
+    h withdraw = fn(amount) { balance = balance - amount; return balance; };
+    h bal      = fn() { return balance; };
+    return [deposit, withdraw, bal];
+}
+
+h acct = make_account(100);
+println(arr_get(acct, 0)(50));   # deposit: 150
+println(arr_get(acct, 1)(30));   # withdraw: 120
+println(arr_get(acct, 2)());     # balance:  120
+```
+
+Architecture changes:
+- `Value::Function.captured`: `Option<HashMap>` → `Option<Rc<RefCell<HashMap>>>`.
+- `Interpreter.locals`: `Vec<HashMap>` → `Vec<Rc<RefCell<HashMap>>>`. Each scope frame is a shareable Rc.
+- Lambda evaluation clones the Rc of the current scope frame (instead of taking a HashMap snapshot). Sibling closures created in the same enclosing call see the SAME underlying map; mutations propagate.
+- New `assign_var` method on Interpreter: walks locals from inner to outer looking for an existing binding; if found, mutates in-place. `Statement::Assignment` now routes through `assign_var` instead of `set_var`. `h x = ...` (declaration) keeps using `set_var` to always create a fresh innermost binding.
+- `call_first_class_function` pushes the captured env Rc as a scope frame BEFORE the args frame, so lookups via lexical chain hit the captured bindings naturally.
+
+The single-closure case (counter pattern) and multi-closure-shared-state (bank account) both work. Refactor touched 9 scope-access sites in `interpreter.rs`. Verified end-to-end with `examples/test_runner.omc` (which uses lambdas internally) and a counter/bank-account smoke test.
+
+#### Track 2 — Module aliasing (`import "path" as alias`)
+
+`import` already parsed an optional `as` clause but the alias was ignored. Now it's wired through:
+
+```omc
+import "examples/math_module.omc" as math;
+println(arr_join(math.fib_up_to(100), ", "));   # 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89
+println(math.euclid_gcd(89, 144));               # 1 (consecutive Fibonacci → coprime)
+```
+
+When an import has an alias, every function the module DEFINES gets renamed to `alias.fname` in the function table. Top-level statements still execute against the global namespace. Re-importing the same path is idempotent (deduped on path, not on alias).
+
+The module resolver gained literal-path support — `import "/abs/path.omc"` and `import "./local.omc"` now work without `OMC_STDLIB_PATH` setup. Still falls back to search-path resolution for short names like `import core` or `import std/io`.
+
+The dotted-call dispatch in `call_module_function` now checks for the full `module.fname` in the user function table BEFORE splitting at `.` and delegating. Otherwise we'd infinite-loop: `call_function("math.fib") → call_module_function("math", "fib") → call_function("math.fib") → …`. Fixed at the entry to `call_function` (check exact name before splitting).
+
+Two new example files:
+- `examples/math_module.omc` — a reusable utility module with `fib_up_to`, `cube_root`, `sum_range`, `euclid_gcd`.
+- `examples/module_demo.omc` — demonstrates `import as` usage and idempotent re-import.
+
+#### Track 3 — Benchmark suite (`examples/benchmarks.omc`)
+
+OMC's first benchmark suite. Times common operations with `now_ms()` and reports per-operation nanoseconds. Run both ways:
+
+```sh
+./target/release/omnimcode-standalone examples/benchmarks.omc           # tree-walk
+OMC_VM=1 ./target/release/omnimcode-standalone examples/benchmarks.omc  # Rust VM
+```
+
+Sample output (tree-walk on a modern laptop):
+
+```
+======================================================================
+OMC Benchmark Suite — N ops, ms total, ns per op
+======================================================================
+int_add (sum 0..N)                200000 iters    89 ms      445 ns/op
+int_mul (sum i*3 0..N)            200000 iters   104 ms      520 ns/op
+str_concat (build N a's)           20000 iters    24 ms     1200 ns/op
+str_split + str_join               20000 iters    28 ms     1400 ns/op
+arr_push + arr_get walk             5000 iters   523 ms   104600 ns/op
+is_fibonacci 0..N                  50000 iters    19 ms      380 ns/op
+harmony_value 0..N                 50000 iters    20 ms      400 ns/op
+recursive fib(N)                      22 iters    53 ms  2409090 ns/op
+======================================================================
+```
+
+**Honest finding** revealed by the benchmark: `OMC_VM=1` produces nearly-identical numbers to tree-walk on this suite. Reason: benchmarks dispatch their bodies via the new `call(fn, args)` primitive, which routes user-function calls through `invoke_user_function` (tree-walk semantics). The VM advantage applies to **direct** `Op::Call` dispatch, not to reflective `call(...)` dispatch.
+
+That's exactly the kind of signal a benchmark suite should produce — concrete data about where the VM helps and where it doesn't. Future work could add a direct-call variant of the suite to isolate the VM hot path.
+
+#### VM gains a first-class-function-value fallback
+
+`Op::LoadVar` in the bytecode VM now falls back to checking `module.functions` AND the interpreter's function table when a name isn't a variable. This makes `arr_map(xs, bench_int_add)` work under `OMC_VM=1` — `bench_int_add` resolves as `Value::Function`. Tree-walk had this fallback already; the VM was missing it.
+
+Also: `main.rs` now calls `vm.interp_mut().register_user_functions(&statements)` before `vm.run_module(...)`, pre-populating the interpreter's function table with user-defined fn bodies so reflective dispatch (`call(name, args)`) can resolve them at runtime.
+
+#### Regression
+
+V.9b: ✓✓✓. H.5: 6/6 demos converge. test_runner: 5/6 (1 intentional failure). safe_keyword_host on both tree-walk and OMC_VM=1: identical output. The 9-site `locals` refactor touched a lot of code but no surface broke.
+
 ### Added (Closures + harmonic_hash/diff/dedupe + test runner — 15 new builtins, 2026-05-14)
 
 🎯 **Three more tracks land: closures over local scope, three new harmonic variants, and a built-in test runner.**

README.md

@@ -48,6 +48,9 @@ What this is **not**: a fast runtime, a production toolchain, a stable API, a de
 | OMNIcode harmonic variants — operations that USE the φ-math substrate | `examples/harmonic_variants.omc` | `harmonic_write_file` gates writes by resonance ≥ 0.5; `harmonic_sort` puts Fibonacci values first; `harmonic_split` chunks strings at φ-aligned word boundaries; `harmonic_partition` buckets by nearest attractor |
 | Closures over local scope (snapshot capture) | `examples/test_runner.omc` | `fn make_adder(n) { return fn(x) { return x + n; }; }` — partial application, currying, captured-state patterns |
 | Built-in test runner | `examples/test_runner.omc` | `fn test_*()` functions auto-discovered via `defined_functions()` and dispatched via `call(name, args)`. `assert_eq` / `assert_array_eq` etc. record failures in host-side state |
+| Mutable closures (Rc<RefCell> shared capture) | `examples/test_runner.omc` | Bank-account pattern: multiple closures from `make_account(100)` share the same `balance` binding; mutations propagate across all of them |
+| Module system with namespace aliasing | `examples/module_demo.omc` | `import "math_module.omc" as math` then `math.fib_up_to(100)` → `0,1,1,2,3,5,8,13,21,34,55,89`. Idempotent re-import; literal-path resolution |
+| Benchmark suite | `examples/benchmarks.omc` | Times `int_add` / `str_concat` / `arr_push` / `recursive fib(22)` / `is_fibonacci` etc. with per-op ns. Run with `OMC_VM=1` to compare against the bytecode VM |
 
 Run any of these with the binary built from this repo:
 

STDLIB.md

@@ -305,16 +305,32 @@ These take ordinary operations and route them through the φ-math substrate. Any
 | `call(fn, args_arr)` | `function, array -> T` | Dispatch a function value (or function-name string) with an arbitrary argument list unpacked from an array. Lets the test runner invoke zero-arg tests; lets user code do dynamic-arity dispatch. |
 | `defined_functions()` | `-> array<string>` | Sorted array of all user-defined function names. Auto-generated `__lambda_N` anonymous functions are excluded. Used by the test runner to discover `test_*` functions. |
 
-Lambdas — `fn(params) { body }` expression form — capture the current local scope by VALUE (snapshot, not reference). Read-only closures over their environment. Mutable closures require shared refs and are future work.
+Lambdas — `fn(params) { body }` expression form — capture the enclosing local scope by REFERENCE (shared `Rc<RefCell>`). Multiple closures created in the same scope share state, and assignments to captured names propagate. Read-and-write closures.
 
 ```omc
-fn make_adder(n) {
-    return fn(x) { return x + n; };
+fn make_counter() {
+    h n = 0;
+    return fn() {
+        n = n + 1;
+        return n;
+    };
+}
+h c = make_counter();
+println(c());    # 1
+println(c());    # 2
+println(c());    # 3
+
+# Multiple closures over shared state — bank account pattern:
+fn make_account(balance) {
+    h deposit  = fn(amount) { balance = balance + amount; return balance; };
+    h withdraw = fn(amount) { balance = balance - amount; return balance; };
+    h bal      = fn() { return balance; };
+    return [deposit, withdraw, bal];
 }
-h add5 = make_adder(5);
-println(add5(10));    # 15
 ```
 
+VM caveat: lambdas execute via tree-walk, not the Rust bytecode VM. The VM's `OMC_VM=1` path bails with an error on `Expression::Lambda` because the bytecode VM has no captured-scope plumbing. Tree-walk works cleanly.
+
 ---
 
 ## Test runner

examples/benchmarks.omc

@@ -0,0 +1,151 @@
+# =============================================================================
+# OMC Benchmark Suite
+# =============================================================================
+# Times common operations and reports per-op nanoseconds. Run both ways
+# to compare the tree-walker vs the bytecode VM:
+#
+#   ./target/release/omnimcode-standalone examples/benchmarks.omc           # tree-walk
+#   OMC_VM=1 ./target/release/omnimcode-standalone examples/benchmarks.omc  # Rust VM
+#
+# Tweak the `iters` constants at the top to scale up/down for your hardware.
+# The default settings put each benchmark in roughly the 100ms-1s range
+# under tree-walk on a modern laptop — short enough to iterate, long enough
+# for `now_ms()` resolution.
+# =============================================================================
+
+# --- Benchmark configuration -----------------------------------------------
+
+h N_INT_OPS    = 200000;   # tight integer arithmetic
+h N_STR_OPS    = 20000;    # string operations (slower per-op)
+h N_ARR_OPS    = 5000;     # array allocations + access
+h N_FIB        = 22;       # recursive fib depth (exponential — keep small)
+h N_RESONANCE  = 50000;    # is_fibonacci / harmony_value calls
+
+# --- Bench harness ---------------------------------------------------------
+# Run a function, time it, return ms elapsed. Uses `call(fn, args_array)`
+# for dispatch (so we can iterate over a list of benchmarks generically).
+
+fn run_bench(label, fn_value, iters) {
+    h start = now_ms();
+    call(fn_value, [iters]);
+    h elapsed_ms = now_ms() - start;
+    # ns per op = ms * 1e6 / iters
+    h ns_per_op = elapsed_ms * 1000000 / iters;
+    println(concat_many(
+        str_pad_right(label, 32, " "),
+        str_pad_left(to_string(iters), 8, " "), " iters  ",
+        str_pad_left(to_string(elapsed_ms), 6, " "), " ms  ",
+        str_pad_left(to_string(ns_per_op), 8, " "), " ns/op"
+    ));
+    return elapsed_ms;
+}
+
+# --- Benchmark bodies ------------------------------------------------------
+
+fn bench_int_add(n) {
+    h i = 0;
+    h sum = 0;
+    while i < n {
+        sum = sum + i;
+        i = i + 1;
+    }
+    return sum;
+}
+
+fn bench_int_mul(n) {
+    h i = 0;
+    h prod = 1;
+    while i < n {
+        prod = prod + (i * 3);
+        i = i + 1;
+    }
+    return prod;
+}
+
+fn bench_str_concat(n) {
+    h s = "";
+    h i = 0;
+    while i < n {
+        s = str_concat(s, "a");
+        i = i + 1;
+    }
+    return str_len(s);
+}
+
+fn bench_str_split_join(n) {
+    h base = "the quick brown fox jumps over the lazy dog";
+    h i = 0;
+    while i < n {
+        h parts = str_split(base, " ");
+        h joined = str_join(parts, ",");
+        i = i + 1;
+    }
+    return n;
+}
+
+fn bench_arr_push_walk(n) {
+    h arr = arr_new(0, 0);
+    h i = 0;
+    while i < n {
+        arr_push(arr, i);
+        i = i + 1;
+    }
+    h sum = 0;
+    h j = 0;
+    while j < arr_len(arr) {
+        sum = sum + arr_get(arr, j);
+        j = j + 1;
+    }
+    return sum;
+}
+
+fn fib(n) {
+    if n < 2 { return n; }
+    return fib(n - 1) + fib(n - 2);
+}
+
+fn bench_recursive_fib(n) {
+    return fib(n);
+}
+
+fn bench_is_fibonacci(n) {
+    h hits = 0;
+    h i = 0;
+    while i < n {
+        if is_fibonacci(i) {
+            hits = hits + 1;
+        }
+        i = i + 1;
+    }
+    return hits;
+}
+
+fn bench_harmony_value(n) {
+    h total = 0;
+    h i = 0;
+    while i < n {
+        h r = harmony_value(i);
+        i = i + 1;
+    }
+    return total;
+}
+
+# --- Run them all ----------------------------------------------------------
+
+println("");
+println(str_repeat("=", 70));
+println("OMC Benchmark Suite — N ops, ms total, ns per op");
+println(str_repeat("=", 70));
+
+run_bench("int_add (sum 0..N)",       bench_int_add,        N_INT_OPS);
+run_bench("int_mul (sum i*3 0..N)",   bench_int_mul,        N_INT_OPS);
+run_bench("str_concat (build N a's)", bench_str_concat,     N_STR_OPS);
+run_bench("str_split + str_join",     bench_str_split_join, N_STR_OPS);
+run_bench("arr_push + arr_get walk",  bench_arr_push_walk,  N_ARR_OPS);
+run_bench("is_fibonacci 0..N",        bench_is_fibonacci,   N_RESONANCE);
+run_bench("harmony_value 0..N",       bench_harmony_value,  N_RESONANCE);
+run_bench("recursive fib(N)",         bench_recursive_fib,  N_FIB);
+
+println(str_repeat("=", 70));
+println("Done. Run with OMC_VM=1 to compare against the Rust bytecode VM.");
+println(str_repeat("=", 70));

examples/math_module.omc

@@ -0,0 +1,57 @@
+# =============================================================================
+# Example module — Fibonacci utilities
+# =============================================================================
+# This file is meant to be imported, not run directly.
+# Use as:
+#   import "examples/math_module.omc" as math;
+#   println(arr_join(math.fib_up_to(100), ","));
+# =============================================================================
+
+# Generate the Fibonacci sequence up to and including the largest value ≤ n.
+fn fib_up_to(n) {
+    h out = arr_new(0, 0);
+    h a = 0;
+    h b = 1;
+    while a <= n {
+        arr_push(out, a);
+        h t = a + b;
+        a = b;
+        b = t;
+    }
+    return out;
+}
+
+# Newton-Raphson cube root. Integer-aligned; precision falls off for
+# non-cubes due to OMC's integer-division semantics, but useful as a
+# demo of how a module exposes mathematical utility functions.
+fn cube_root(x) {
+    h r = x / 3;
+    h i = 0;
+    while i < 8 {
+        r = r - (r * r * r - x) / (3 * r * r);
+        i = i + 1;
+    }
+    return r;
+}
+
+# Sum the elements of an integer range [lo, hi] inclusive.
+fn sum_range(lo, hi) {
+    h total = 0;
+    h k = lo;
+    while k <= hi {
+        total = total + k;
+        k = k + 1;
+    }
+    return total;
+}
+
+# Greatest common divisor — already a built-in in core, but useful as a
+# pedagogical example for how a module reimplements / overrides.
+fn euclid_gcd(a, b) {
+    while b != 0 {
+        h t = b;
+        b = a % b;
+        a = t;
+    }
+    return a;
+}

examples/module_demo.omc

@@ -0,0 +1,27 @@
+# =============================================================================
+# Module system demo — import-with-alias
+# =============================================================================
+# Run as:
+#   ./target/release/omnimcode-standalone examples/module_demo.omc
+# =============================================================================
+
+# Plain `import "path"` merges the module's functions into the global namespace.
+# `import "path" as alias` registers them as `alias.fname` so they're reached
+# via dotted-call syntax. Re-importing the same path is a no-op (idempotent).
+
+import "examples/math_module.omc" as math;
+
+# Every defined function in the module is reachable under `math.`:
+println(concat_many("First 100 Fibonacci numbers <= 100: ",
+                    arr_join(math.fib_up_to(100), ", ")));
+
+println(concat_many("sum_range(1, 10) = ", math.sum_range(1, 10)));
+println(concat_many("euclid_gcd(89, 144) = ", math.euclid_gcd(89, 144)));
+println(concat_many("cube_root(27) ≈ ", math.cube_root(27)));
+
+# Re-importing the same module is idempotent — no double-execute, no
+# namespace conflict, no extra cost. The dedup key is the module path
+# (not the alias), so a second import call returns immediately. If you
+# need two namespaces over the same code, point them at different files.
+import "examples/math_module.omc" as math;
+println("re-import was idempotent (no-op)");