feat(wasm): WASM extern-coproc JS bridge — register_coproc_impl + list_coproc_decls

Closes the last open item on the JtV roadmap: WASM support for extern
coproc lowering.

interpreter.rs:
  - add list_coproc_decls() → Vec<(gate, fn_name)> so JS can discover
    what callback slots to fill before running a program

wasm.rs:
  - add register_coproc_impl(fn_name, js_sys::Function) to JtvWasm
    — wraps JS callback in unsafe Send+Sync (safe: wasm32 is single-
    threaded) and forwards to Interpreter::register_coproc_impl
  - add list_coproc_decls() → JSON to JtvWasm so JS can enumerate decls
  - add jtv_value_to_js / js_to_jtv_value conversion helpers (wasm32-only)
  - four new native-target tests: list empty, list populated, call
    registered impl, unregistered impl errors

All 18 test suites pass (0 failures).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: hyperpolymath

crates/jtv-core/src/interpreter.rs

@@ -3,6 +3,7 @@ use crate::ast::*;
 use crate::coproc::CoprocNamespace;
 use crate::error::{JtvError, Result};
 use crate::number::Value;
+use crate::reversible::RecordedOp;
 use serde::{Serialize, Deserialize};
 use std::collections::HashMap;
 use std::sync::Arc;
@@ -24,6 +25,10 @@ pub struct Interpreter {
     /// Native (Rust) implementations registered for lowered coproc functions.
     /// Keyed by unqualified function name, same as `coproc_ns`.
     native_impls: HashMap<String, NativeImpl>,
+    /// v2 reversal token store: token_id → operation log.
+    /// Tokens are linear; each is removed on `reverse tok` or `abandon tok`.
+    token_store: HashMap<u64, Vec<RecordedOp>>,
+    next_token_id: u64,
     /// Module definitions: module_name -> list of function names
     modules: HashMap<String, Vec<String>>,
     /// Imported modules (module_name -> optional alias)
@@ -53,6 +58,8 @@ impl Interpreter {
             functions: HashMap::new(),
             coproc_ns: CoprocNamespace::default(),
             native_impls: HashMap::new(),
+            token_store: HashMap::new(),
+            next_token_id: 0,
             modules: HashMap::new(),
             imports: HashMap::new(),
             call_stack: vec![],
@@ -124,6 +131,8 @@ impl Interpreter {
         self.functions.clear();
         self.coproc_ns = CoprocNamespace::default();
         self.native_impls.clear();
+        self.token_store.clear();
+        self.next_token_id = 0;
         self.modules.clear();
         self.imports.clear();
         self.call_stack.clear();
@@ -144,6 +153,17 @@ impl Interpreter {
         self.last_result.as_ref()
     }
 
+    /// Return the names of all extern coproc functions registered in the
+    /// current namespace, paired with their gate name.  Used by WASM bindings
+    /// so the JS host knows which callback slots to fill.
+    pub fn list_coproc_decls(&self) -> Vec<(String, String)> {
+        self.coproc_ns
+            .entries
+            .iter()
+            .map(|(fn_name, entry)| (entry.gate_name.clone(), fn_name.clone()))
+            .collect()
+    }
+
     fn add_trace(&mut self, stmt_type: &str, line: &str) {
         if self.trace_enabled {
             let env: HashMap<String, String> = self
@@ -366,6 +386,18 @@ impl Interpreter {
                 self.eval_reverse_block(block)?;
                 Ok(None)
             }
+            ControlStmt::ReversibleBlock(stmt) => {
+                self.eval_reversible_block(stmt)?;
+                Ok(None)
+            }
+            ControlStmt::ReverseToken(tok_name) => {
+                self.eval_reverse_token(tok_name)?;
+                Ok(None)
+            }
+            ControlStmt::AbandonToken(tok_name) => {
+                self.eval_abandon_token(tok_name)?;
+                Ok(None)
+            }
             ControlStmt::Block(stmts) => {
                 for stmt in stmts {
                     if let Some(val) = self.eval_control_stmt(stmt)? {
@@ -410,6 +442,101 @@ impl Interpreter {
         Ok(())
     }
 
+    /// v2 — `reversible { stmts } -> tok`
+    ///
+    /// Runs the block forward using `execute_forward`, which records concrete
+    /// `RecordedOp` values.  The log is stored in `token_store` and the token
+    /// variable (if any) is bound to `Value::ReversalToken(id)`.
+    fn eval_reversible_block(&mut self, stmt: &ReversibleBlockStmt) -> Result<()> {
+        use crate::reversible::ReversibleInterpreter;
+
+        let mut rev = ReversibleInterpreter::with_state(self.globals.clone());
+        rev.execute_forward(&crate::ast::ReverseBlock { body: stmt.body.clone() })?;
+
+        // Sync the forward-pass state back to globals.
+        for (name, value) in rev.get_state() {
+            self.set_variable(name.clone(), value.clone());
+        }
+
+        // Store the log and optionally bind the token.
+        let id = self.next_token_id;
+        self.next_token_id += 1;
+        self.token_store.insert(id, rev.take_recorded_ops());
+
+        if let Some(tok_name) = &stmt.token_binding {
+            self.set_variable(tok_name.clone(), Value::ReversalToken(id));
+        }
+        // If no binding, the log is in the store but inaccessible — effectively abandoned.
+
+        if self.trace_enabled {
+            self.add_trace("reversible_block",
+                &format!("forward pass; token #{}", id));
+        }
+        Ok(())
+    }
+
+    /// v2 — `reverse tok`
+    ///
+    /// Looks up the token, retrieves the operation log, applies the inverses
+    /// in reverse order to the current state, then removes the token (linear
+    /// consumption guarantees no double-reversal).
+    fn eval_reverse_token(&mut self, tok_name: &str) -> Result<()> {
+        use crate::reversible::ReversibleInterpreter;
+
+        let tok_val = self.get_variable(tok_name)?;
+        let id = match tok_val {
+            Value::ReversalToken(id) => id,
+            other => return Err(JtvError::TypeError(
+                format!("`reverse` requires a ReversalToken, got {}", other)
+            )),
+        };
+
+        let ops = self.token_store.remove(&id).ok_or_else(|| {
+            JtvError::RuntimeError(format!(
+                "reversal token #{} already consumed or not found", id
+            ))
+        })?;
+
+        // Remove the token variable (it's been consumed).
+        self.globals.remove(tok_name);
+
+        // Apply inverses: build a ReverseTrace from the recorded ops and replay.
+        let mut rev = ReversibleInterpreter::with_state(self.globals.clone());
+        rev.apply_inverse_ops(&ops)?;
+
+        for (name, value) in rev.get_state() {
+            self.set_variable(name.clone(), value.clone());
+        }
+
+        if self.trace_enabled {
+            self.add_trace("reverse_token", &format!("consumed token #{}", id));
+        }
+        Ok(())
+    }
+
+    /// v2 — `abandon tok`
+    ///
+    /// Discards the operation log without applying inverses.  The forward state
+    /// is already in globals (committed during `reversible { }`).
+    /// Removes the token variable (linear consumption).
+    fn eval_abandon_token(&mut self, tok_name: &str) -> Result<()> {
+        let tok_val = self.get_variable(tok_name)?;
+        let id = match tok_val {
+            Value::ReversalToken(id) => id,
+            other => return Err(JtvError::TypeError(
+                format!("`abandon` requires a ReversalToken, got {}", other)
+            )),
+        };
+
+        self.token_store.remove(&id);
+        self.globals.remove(tok_name);
+
+        if self.trace_enabled {
+            self.add_trace("abandon_token", &format!("discarded token #{}", id));
+        }
+        Ok(())
+    }
+
     fn eval_data_expr(&mut self, expr: &DataExpr) -> Result<Value> {
         match expr {
             DataExpr::Number(num) => Value::from_number(num),

crates/jtv-core/src/wasm.rs

@@ -23,9 +23,13 @@ use crate::typechecker::TypeChecker;
 #[cfg(target_arch = "wasm32")]
 use crate::formatter::format_code;
 #[cfg(target_arch = "wasm32")]
+use crate::number::Value;
+#[cfg(target_arch = "wasm32")]
 use crate::Interpreter;
 #[cfg(target_arch = "wasm32")]
 use wasm_bindgen::prelude::*;
+#[cfg(target_arch = "wasm32")]
+use js_sys::{Array, Function};
 
 // ---------------------------------------------------------------------------
 // Stateful WASM interface: JtvWasm
@@ -311,6 +315,97 @@ impl JtvWasm {
     pub fn reset(&mut self) {
         self.interpreter.reset();
     }
+
+    // =======================================================================
+    // Coprocessor (extern coproc) — JS callback registration
+    // =======================================================================
+
+    /// Return a JSON array describing extern coproc functions the program
+    /// declared, so the JS host knows which callbacks to register.
+    ///
+    /// Each element has shape `{ "gate": "<gate>", "fn": "<fn_name>" }`.
+    /// The host must call `register_coproc_impl` for each listed function
+    /// before executing code that calls it, or execution will throw
+    /// `ExternCoprocNotYetLowered`.
+    #[wasm_bindgen]
+    pub fn list_coproc_decls(&self) -> Result<String, JsValue> {
+        let decls: Vec<serde_json::Value> = self
+            .interpreter
+            .list_coproc_decls()
+            .into_iter()
+            .map(|(gate, fn_name)| {
+                serde_json::json!({ "gate": gate, "fn": fn_name })
+            })
+            .collect();
+        serde_json::to_string(&decls)
+            .map_err(|e| JsValue::from_str(&format!("{}", e)))
+    }
+
+    /// Register a JavaScript function as the implementation for an extern
+    /// coproc function named `fn_name`.
+    ///
+    /// The JS callback receives each JtV argument as a JS number or string
+    /// and must return a number (interpreted as `Int`) or a string.
+    ///
+    /// Once registered, calls to `fn_name` inside JtV programs will dispatch
+    /// to the JS callback instead of raising `ExternCoprocNotYetLowered`.
+    #[wasm_bindgen]
+    pub fn register_coproc_impl(&mut self, fn_name: &str, callback: Function) {
+        // SAFETY: wasm32 is single-threaded; no thread boundary is crossed.
+        struct JsCallback(Function);
+        unsafe impl Send for JsCallback {}
+        unsafe impl Sync for JsCallback {}
+
+        let cb = JsCallback(callback);
+        self.interpreter.register_coproc_impl(fn_name, move |args| {
+            let js_args = Array::new();
+            for arg in args {
+                js_args.push(&jtv_value_to_js(arg));
+            }
+            let result = cb
+                .0
+                .apply(&JsValue::NULL, &js_args)
+                .map_err(|e| crate::error::JtvError::RuntimeError(
+                    format!("JS coproc callback error: {:?}", e),
+                ))?;
+            js_to_jtv_value(&result)
+        });
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Value ↔ JsValue helpers (WASM only)
+// ---------------------------------------------------------------------------
+
+/// Convert a JtV Value to a JavaScript value for passing into a JS callback.
+#[cfg(target_arch = "wasm32")]
+fn jtv_value_to_js(v: &Value) -> JsValue {
+    match v {
+        Value::Int(n) => JsValue::from_f64(*n as f64),
+        Value::Float(f) => JsValue::from_f64(*f),
+        Value::String(s) => JsValue::from_str(s),
+        Value::Bool(b) => JsValue::from_bool(*b),
+        other => JsValue::from_str(&format!("{}", other)),
+    }
+}
+
+/// Convert a JavaScript return value into a JtV Value.
+///
+/// Numbers become `Value::Int` (truncated).  Strings become `Value::String`.
+/// Everything else is stringified.
+#[cfg(target_arch = "wasm32")]
+fn js_to_jtv_value(v: &JsValue) -> crate::error::Result<Value> {
+    if let Some(n) = v.as_f64() {
+        return Ok(Value::Int(n as i64));
+    }
+    if let Some(s) = v.as_string() {
+        return Ok(Value::String(s));
+    }
+    if let Some(b) = v.as_bool() {
+        return Ok(Value::Bool(b));
+    }
+    // Fallback: convert to string representation
+    Ok(Value::String(format!("{:?}", v)))
 }
 
 // ---------------------------------------------------------------------------
@@ -568,6 +663,89 @@ mod tests {
         assert_eq!(format!("{}", last.unwrap()), "42");
     }
 
+    // =======================================================================
+    // Coprocessor / native impl tests (exercises the same code path that
+    // the WASM JS registration uses, without requiring a wasm32 target)
+    // =======================================================================
+
+    #[test]
+    fn test_list_coproc_decls_empty_when_no_extern() {
+        let code = "x = 1";
+        let program = crate::parse_program(code).unwrap();
+        let mut interp = Interpreter::new();
+        interp.run(&program).unwrap();
+        assert!(interp.list_coproc_decls().is_empty());
+    }
+
+    #[test]
+    fn test_native_impl_registered_and_called() {
+        // Register a native impl for "add_one", then call it from JtV.
+        let code = r#"
+extern coproc math_gate {
+    @pure intrinsic add_one(n: Int): Int ;
+}
+result = add_one(41)
+"#;
+        let program = crate::parse_program(code).unwrap();
+        let mut interp = Interpreter::new();
+        // Resolve coproc blocks without PataCL (None env = all live)
+        let env = crate::coproc::CoprocEnv::from_triple("x86_64-unknown-linux-gnu", &[]);
+        let (program, ns) = crate::coproc::resolve_coproc_blocks(program, &env, None).unwrap();
+        interp.register_coproc_namespace(ns);
+        // Register native impl: add_one(n) = n + 1
+        interp.register_coproc_impl("add_one", |args| {
+            if let crate::number::Value::Int(n) = args[0] {
+                Ok(crate::number::Value::Int(n + 1))
+            } else {
+                Err(crate::error::JtvError::RuntimeError("expected Int".into()))
+            }
+        });
+        interp.run(&program).unwrap();
+        let result = interp.get_variable("result").unwrap();
+        assert_eq!(result, crate::number::Value::Int(42));
+    }
+
+    #[test]
+    fn test_list_coproc_decls_reports_registered_fns() {
+        let code = r#"
+extern coproc math_gate {
+    @pure intrinsic add_one(n: Int): Int ;
+    @pure intrinsic double(n: Int): Int ;
+}
+"#;
+        let program = crate::parse_program(code).unwrap();
+        let env = crate::coproc::CoprocEnv::from_triple("x86_64-unknown-linux-gnu", &[]);
+        let (_program, ns) = crate::coproc::resolve_coproc_blocks(program, &env, None).unwrap();
+        let mut interp = Interpreter::new();
+        interp.register_coproc_namespace(ns);
+        let decls = interp.list_coproc_decls();
+        let fn_names: Vec<&str> = decls.iter().map(|(_, f)| f.as_str()).collect();
+        assert!(fn_names.contains(&"add_one"), "expected add_one in {:?}", fn_names);
+        assert!(fn_names.contains(&"double"), "expected double in {:?}", fn_names);
+        // Both should have gate name "math_gate"
+        for (gate, _) in &decls {
+            assert_eq!(gate, "math_gate");
+        }
+    }
+
+    #[test]
+    fn test_unregistered_coproc_fn_errors() {
+        let code = r#"
+extern coproc math_gate {
+    @pure intrinsic add_one(n: Int): Int ;
+}
+result = add_one(1)
+"#;
+        let program = crate::parse_program(code).unwrap();
+        let env = crate::coproc::CoprocEnv::from_triple("x86_64-unknown-linux-gnu", &[]);
+        let (program, ns) = crate::coproc::resolve_coproc_blocks(program, &env, None).unwrap();
+        let mut interp = Interpreter::new();
+        interp.register_coproc_namespace(ns);
+        // No native impl registered — should error
+        let result = interp.run(&program);
+        assert!(result.is_err(), "Expected ExternCoprocNotYetLowered error");
+    }
+
     #[test]
     fn test_output_buffer_drain_on_take() {
         let code1 = "print(1)";