feat(vm): upvalue capture for closures (by value, single level) (#94)

## What

Adds **upvalue capture** to VM closures — the deferred follow-up from
#93. Previously a lambda could only use its params + globals;
referencing an enclosing local compiled to a `LoadGlobal` that failed at
runtime. Now closures capture enclosing locals.

- **Compiler**: the flat locals list becomes a **stack of scopes**. A
lambda pushes a scope; the enclosing scope stays visible. Name
resolution is now: `LoadLocal` (current scope) → `LoadUpvalue` (captured
from the enclosing scope, recorded + deduped) → `LoadGlobal`. The lambda
emits `MakeClosure(func_idx, upvalue_srcs)`.
- **Value**: `VmClosure` now carries `{ func_idx, upvalues: Vec<Value>
}` (was just an index); the 5 exhaustive `Value` matches updated.
- **bytecode**: `MakeClosure(usize, Vec<usize>)` + new
`LoadUpvalue(usize)`.
- **machine**: `CallFrame` carries `upvalues`; `MakeClosure` captures
the listed enclosing locals **by value**; `CallValue` installs the
closure's upvalues into the new frame; `LoadUpvalue` reads them.

## Verification
- **Full lib suite green: 188 passed, 0 failed** (+2 tests).
- New tests: `(|x| x + n)(5)` → 15 (single capture); `(|x| x + a +
b)(3)` → 123 (multiple).
- `rustfmt` + `clippy` (CI mode) clean.

## Scope (documented limitations → follow-ups)
- **By-value capture**: the closure snapshots captured values at
creation; mutation *through* a captured variable isn't reflected back to
the enclosing scope. (The interpreter captures by reference via a shared
env; matching that needs reference cells.)
- **Single-level nesting**: a lambda captures its immediate enclosing
function's locals, not a grand-enclosing scope (no recursive upvalue
threading yet).

## Remaining VM follow-ups
By-reference / multi-level capture · interpreter↔VM parity harness ·
`.wbc` serialization · worker statements · consent grant-sources.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_013wg3Mtq2QFhYi4XVw1Z6z7

---
_Generated by [Claude
Code](https://claude.ai/code/session_013wg3Mtq2QFhYi4XVw1Z6z7)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

src/interpreter/mod.rs

@@ -1056,7 +1056,7 @@ impl Interpreter {
             Value::Okay(inner) => format!("Okay({})", self.value_to_string(inner)),
             Value::Oops(msg) => format!("Oops({})", msg),
             Value::Channel(_) => "<channel>".to_string(),
-            Value::VmClosure(_) => "<vm-closure>".to_string(),
+            Value::VmClosure { .. } => "<vm-closure>".to_string(),
         }
     }
 }

src/interpreter/value.rs

@@ -223,9 +223,12 @@ pub enum Value {
     Function(Closure),
     /// Go-style channel for concurrent communication
     Channel(ChannelHandle),
-    /// A VM bytecode closure: an index into the compiled function table.
-    /// Non-capturing for now (uses params + globals, not enclosing locals).
-    VmClosure(usize),
+    /// A VM bytecode closure: a function-table index plus captured upvalues
+    /// (enclosing locals captured by value at closure-creation time).
+    VmClosure {
+        func_idx: usize,
+        upvalues: Vec<Value>,
+    },
 }
 
 impl Value {
@@ -243,7 +246,7 @@ impl Value {
             Value::Oops(_) => false,
             Value::Function(_) => true,
             Value::Channel(ch) => !ch.is_closed(),
-            Value::VmClosure(_) => true,
+            Value::VmClosure { .. } => true,
         }
     }
 
@@ -308,7 +311,7 @@ impl fmt::Display for Value {
                     None => write!(f, "<chan {}>", status),
                 }
             }
-            Value::VmClosure(idx) => write!(f, "<vm-closure {}>", idx),
+            Value::VmClosure { func_idx, .. } => write!(f, "<vm-closure {}>", func_idx),
         }
     }
 }

src/repl.rs

@@ -85,7 +85,9 @@ impl Repl {
                     crate::interpreter::Value::Float(f) => println!("{}", f),
                     crate::interpreter::Value::String(s) => println!("\"{}\"", s),
                     crate::interpreter::Value::Bool(b) => println!("{}", b),
-                    crate::interpreter::Value::VmClosure(idx) => println!("<vm-closure {}>", idx),
+                    crate::interpreter::Value::VmClosure { func_idx, .. } => {
+                        println!("<vm-closure {}>", func_idx)
+                    }
                     crate::interpreter::Value::Array(arr) => {
                         print!("[");
                         for (i, val) in arr.iter().enumerate() {

src/stdlib/json.rs

@@ -147,7 +147,7 @@ fn value_to_json_string(value: &Value) -> Result<String, StdlibError> {
         Value::Okay(_) | Value::Oops(_) => Err(StdlibError::RuntimeError(
             "Cannot stringify Result to JSON".to_string(),
         )),
-        Value::VmClosure(_) => Err(StdlibError::RuntimeError(
+        Value::VmClosure { .. } => Err(StdlibError::RuntimeError(
             "Cannot stringify closure to JSON".to_string(),
         )),
     }

src/vm/bytecode.rs

@@ -69,10 +69,13 @@ pub enum OpCode {
     Call(usize),
     /// Return from function
     Return,
-    /// Create a closure: push a `VmClosure` for the given function index
-    MakeClosure(usize),
+    /// Create a closure: push a `VmClosure` for the given function index,
+    /// capturing the listed enclosing locals (by stack index, by value).
+    MakeClosure(usize, Vec<usize>),
     /// Call a closure value sitting just below its `usize` arguments on the stack
     CallValue(usize),
+    /// Load captured upvalue `usize` of the executing closure onto the stack
+    LoadUpvalue(usize),
 
     // Array/Record operations
     /// Create an array from N elements on stack

src/vm/compiler.rs

@@ -40,13 +40,31 @@ struct LoopCtx {
     break_jumps: Vec<usize>,
 }
 
+/// A lexical scope (a function or lambda body): its locals plus the upvalues it
+/// captures from the immediately enclosing scope (recorded as enclosing-local
+/// indices, captured by value).
+struct Scope {
+    locals: Vec<Local>,
+    upvalues: Vec<usize>,
+}
+
+impl Scope {
+    fn new() -> Self {
+        Self {
+            locals: Vec::new(),
+            upvalues: Vec::new(),
+        }
+    }
+}
+
 /// Compiler state
 pub struct BytecodeCompiler {
     /// Current function being compiled
     current_function: Option<CompiledFunction>,
-    /// Local variables in current scope
-    locals: Vec<Local>,
-    /// Current scope depth
+    /// Stack of lexical scopes; the top is the current scope. Lambdas push a
+    /// scope so they can capture upvalues from the enclosing scope.
+    scopes: Vec<Scope>,
+    /// Current scope depth (used only for lambda naming).
     scope_depth: usize,
     /// Function names to indices
     function_indices: HashMap<String, usize>,
@@ -60,7 +78,7 @@ impl BytecodeCompiler {
     pub fn new() -> Self {
         Self {
             current_function: None,
-            locals: Vec::new(),
+            scopes: vec![Scope::new()],
             scope_depth: 0,
             function_indices: HashMap::new(),
             program: CompiledProgram::new(),
@@ -128,7 +146,7 @@ impl BytecodeCompiler {
         compiled_func: &mut CompiledFunction,
     ) -> Result<(), CompileError> {
         self.current_function = Some(compiled_func.clone());
-        self.locals.clear();
+        self.scopes = vec![Scope::new()];
         self.scope_depth = 0;
 
         // Add parameters as locals
@@ -528,6 +546,8 @@ impl BytecodeCompiler {
             Expr::Identifier(name) => {
                 if let Some(local_idx) = self.resolve_local(name) {
                     func.emit(OpCode::LoadLocal(local_idx));
+                } else if let Some(upvalue_idx) = self.resolve_upvalue(name) {
+                    func.emit(OpCode::LoadUpvalue(upvalue_idx));
                 } else {
                     func.emit(OpCode::LoadGlobal(name.clone()));
                 }
@@ -681,9 +701,10 @@ impl BytecodeCompiler {
                 let lambda_name = format!("<lambda_{}>", self.scope_depth);
                 let mut lambda_func = CompiledFunction::new(lambda_name, lambda.params.len());
 
-                // Enter new scope for lambda
+                // Enter a new scope; the enclosing scope stays accessible for
+                // upvalue capture.
                 self.scope_depth += 1;
-                let old_locals = std::mem::take(&mut self.locals);
+                self.scopes.push(Scope::new());
 
                 // Add parameters as locals
                 for param in &lambda.params {
@@ -708,15 +729,14 @@ impl BytecodeCompiler {
                     }
                 }
 
-                // Restore scope
+                // Pop the lambda scope, recovering the upvalues it captured.
+                let lambda_scope = self.scopes.pop().expect("lambda scope");
                 self.scope_depth -= 1;
-                self.locals = old_locals;
 
-                // Add lambda function to program
+                // Add the lambda to the program and create a closure that
+                // captures the recorded enclosing locals by value.
                 let func_idx = self.program.add_function(lambda_func);
-
-                // Create closure from function
-                func.emit(OpCode::MakeClosure(func_idx));
+                func.emit(OpCode::MakeClosure(func_idx, lambda_scope.upvalues));
                 Ok(())
             }
 
@@ -758,25 +778,55 @@ impl BytecodeCompiler {
         }
     }
 
-    /// Add a local variable
+    /// Add a local variable to the current scope.
     fn add_local(&mut self, name: String) -> usize {
-        let idx = self.locals.len();
-        self.locals.push(Local {
-            name,
-            depth: self.scope_depth,
-        });
+        let depth = self.scope_depth;
+        let scope = self.scopes.last_mut().expect("at least one scope");
+        let idx = scope.locals.len();
+        scope.locals.push(Local { name, depth });
         idx
     }
 
-    /// Resolve a local variable by name
+    /// Resolve a local variable by name in the current scope.
     fn resolve_local(&self, name: &str) -> Option<usize> {
-        for (idx, local) in self.locals.iter().enumerate().rev() {
+        let scope = self.scopes.last()?;
+        for (idx, local) in scope.locals.iter().enumerate().rev() {
             if local.name == name {
                 return Some(idx);
             }
         }
         None
     }
+
+    /// Resolve `name` as an upvalue captured from the immediately enclosing
+    /// scope. Registers the capture (deduplicated) in the current scope and
+    /// returns its upvalue index. Single-level capture only.
+    fn resolve_upvalue(&mut self, name: &str) -> Option<usize> {
+        let n = self.scopes.len();
+        if n < 2 {
+            return None;
+        }
+        // Find `name` among the immediately enclosing scope's locals.
+        let enclosing_local = {
+            let enclosing = &self.scopes[n - 2];
+            let mut found = None;
+            for (idx, local) in enclosing.locals.iter().enumerate().rev() {
+                if local.name == name {
+                    found = Some(idx);
+                    break;
+                }
+            }
+            found?
+        };
+        // Register (or reuse) an upvalue capturing that enclosing local.
+        let scope = self.scopes.last_mut().unwrap();
+        if let Some(uidx) = scope.upvalues.iter().position(|&s| s == enclosing_local) {
+            return Some(uidx);
+        }
+        let uidx = scope.upvalues.len();
+        scope.upvalues.push(enclosing_local);
+        Some(uidx)
+    }
 }
 
 impl Default for BytecodeCompiler {

src/vm/machine.rs

@@ -51,6 +51,8 @@ struct CallFrame {
     ip: usize,
     /// Base pointer for locals (points into value stack)
     bp: usize,
+    /// Captured upvalues, if this frame is executing a closure (else empty)
+    upvalues: Vec<Value>,
 }
 
 /// The virtual machine
@@ -90,6 +92,7 @@ impl VirtualMachine {
             function_idx: entry_idx,
             ip: 0,
             bp: 0,
+            upvalues: Vec::new(),
         });
 
         // Execute
@@ -312,6 +315,7 @@ impl VirtualMachine {
                         function_idx: callee_idx,
                         ip: 0,
                         bp,
+                        upvalues: Vec::new(),
                     });
                 }
 
@@ -469,23 +473,46 @@ impl VirtualMachine {
                     self.push(Value::Bool(granted));
                 }
 
-                OpCode::MakeClosure(func_idx) => {
-                    // Non-capturing closure: just the bytecode function index.
-                    self.push(Value::VmClosure(func_idx));
+                OpCode::MakeClosure(func_idx, upvalue_srcs) => {
+                    // Capture the listed enclosing locals by value from the
+                    // current frame's locals (stack[bp + src]).
+                    let bp = self.frames.last().ok_or(VMError::InvalidIP)?.bp;
+                    let mut upvalues = Vec::with_capacity(upvalue_srcs.len());
+                    for src in &upvalue_srcs {
+                        let v = self
+                            .stack
+                            .get(bp + *src)
+                            .ok_or(VMError::InvalidLocalIndex(*src))?
+                            .clone();
+                        upvalues.push(v);
+                    }
+                    self.push(Value::VmClosure { func_idx, upvalues });
+                }
+
+                OpCode::LoadUpvalue(idx) => {
+                    let value = self
+                        .frames
+                        .last()
+                        .ok_or(VMError::InvalidIP)?
+                        .upvalues
+                        .get(idx)
+                        .ok_or(VMError::InvalidLocalIndex(idx))?
+                        .clone();
+                    self.push(value);
                 }
 
                 OpCode::CallValue(argc) => {
                     // Stack: [callee_closure, arg0, .., arg{argc-1}]. Remove the
                     // closure from below the args, then enter its frame with the
-                    // args as locals 0..argc.
+                    // args as locals 0..argc and the closure's captured upvalues.
                     let cpos = self
                         .stack
                         .len()
                         .checked_sub(argc + 1)
                         .ok_or(VMError::StackUnderflow)?;
                     let callee = self.stack.remove(cpos);
-                    let func_idx = match callee {
-                        Value::VmClosure(idx) => idx,
+                    let (func_idx, upvalues) = match callee {
+                        Value::VmClosure { func_idx, upvalues } => (func_idx, upvalues),
                         other => {
                             return Err(VMError::TypeError(format!(
                                 "cannot call non-closure value: {:?}",
@@ -500,6 +527,7 @@ impl VirtualMachine {
                         function_idx: func_idx,
                         ip: 0,
                         bp: cpos,
+                        upvalues,
                     });
                 }
             }

src/vm/mod.rs

@@ -311,4 +311,28 @@ mod tests {
         "#;
         assert_eq!(run_vm(source).unwrap(), Value::Int(42));
     }
+
+    #[test]
+    fn test_vm_closure_captures_upvalue() {
+        // The lambda captures the enclosing local `n` (= 10) by value.
+        let source = r#"
+            to main() {
+                remember n = 10;
+                give back (|x| x + n)(5);
+            }
+        "#;
+        assert_eq!(run_vm(source).unwrap(), Value::Int(15));
+    }
+
+    #[test]
+    fn test_vm_closure_captures_multiple() {
+        let source = r#"
+            to main() {
+                remember a = 100;
+                remember b = 20;
+                give back (|x| x + a + b)(3);
+            }
+        "#;
+        assert_eq!(run_vm(source).unwrap(), Value::Int(123));
+    }
 }