feat: US-062 - Add stub bridge context and registration for snapshot creation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: NathanFlurry

crates/v8-runtime/src/bridge.rs

@@ -410,6 +410,43 @@ fn async_bridge_callback(
     rv.set(promise.into());
 }
 
+/// Register stub bridge functions on the V8 global for snapshot creation.
+///
+/// Uses the same sync_bridge_callback / async_bridge_callback as real
+/// functions (required for ExternalReferences in snapshot serialization)
+/// but WITHOUT v8::External data. If a stub is accidentally called during
+/// snapshot creation, the callback gracefully throws a V8 exception
+/// (args.data() is not External -> "missing bridge function data" error).
+///
+/// After snapshot restore, these stubs are replaced with real functions
+/// that have proper External data pointing to a session-local BridgeCallContext.
+pub fn register_stub_bridge_fns(
+    scope: &mut v8::HandleScope,
+    sync_fns: &[&str],
+    async_fns: &[&str],
+) {
+    let context = scope.get_current_context();
+    let global = context.global(scope);
+
+    // Register sync bridge functions as stubs (no External data)
+    for &method_name in sync_fns {
+        let template = v8::FunctionTemplate::builder(sync_bridge_callback)
+            .build(scope);
+        let func = template.get_function(scope).unwrap();
+        let key = v8::String::new(scope, method_name).unwrap();
+        global.set(scope, key.into(), func.into());
+    }
+
+    // Register async bridge functions as stubs (no External data)
+    for &method_name in async_fns {
+        let template = v8::FunctionTemplate::builder(async_bridge_callback)
+            .build(scope);
+        let func = template.get_function(scope).unwrap();
+        let key = v8::String::new(scope, method_name).unwrap();
+        global.set(scope, key.into(), func.into());
+    }
+}
+
 /// Serialize V8 function arguments into a pre-allocated buffer.
 /// The buffer is cleared and reused across calls (grows to high-water mark).
 fn serialize_v8_args_into(scope: &mut v8::HandleScope, args: &v8::FunctionCallbackArguments, buf: &mut Vec<u8>) -> Result<(), String> {

crates/v8-runtime/src/host_call.rs

@@ -111,7 +111,41 @@ pub struct BridgeCallContext {
     call_id_router: Option<CallIdRouter>,
 }
 
+/// No-op FrameSender for snapshot stub functions.
+/// Panics if called — stubs must never be invoked during snapshot creation.
+struct StubFrameSender;
+
+impl FrameSender for StubFrameSender {
+    fn send_frame(&self, _frame: &BinaryFrame) -> Result<(), String> {
+        panic!("stub bridge function called during snapshot creation — bridge IIFE must not call bridge functions at setup time")
+    }
+}
+
+/// No-op ResponseReceiver for snapshot stub functions.
+/// Panics if called — stubs must never be invoked during snapshot creation.
+struct StubResponseReceiver;
+
+impl ResponseReceiver for StubResponseReceiver {
+    fn recv_response(&self) -> Result<BinaryFrame, String> {
+        panic!("stub bridge function called during snapshot creation — bridge IIFE must not call bridge functions at setup time")
+    }
+}
+
 impl BridgeCallContext {
+    /// Create a no-op BridgeCallContext for snapshot stub functions.
+    /// Panics if sync_call or async_send is called — stubs exist only for
+    /// the bridge IIFE to reference (not call) during snapshot creation.
+    pub fn stub() -> Self {
+        BridgeCallContext {
+            sender: Box::new(StubFrameSender),
+            response_rx: Mutex::new(Box::new(StubResponseReceiver)),
+            session_id: "stub".into(),
+            next_call_id: AtomicU64::new(1),
+            pending_calls: Mutex::new(HashSet::new()),
+            call_id_router: None,
+        }
+    }
+
     /// Create a BridgeCallContext with a byte writer and reader (wraps in WriterFrameSender
     /// and ReaderResponseReceiver). Convenient for tests that pre-serialize BridgeResponse bytes.
     pub fn new(
@@ -637,4 +671,22 @@ mod tests {
         let decoded = ipc_binary::read_frame(&mut Cursor::new(&bytes)).expect("decode");
         assert_eq!(decoded, small);
     }
+
+    #[test]
+    fn stub_context_panics_on_sync_call() {
+        let ctx = BridgeCallContext::stub();
+        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+            let _ = ctx.sync_call("_fsReadFile", vec![]);
+        }));
+        assert!(result.is_err(), "stub sync_call should panic");
+    }
+
+    #[test]
+    fn stub_context_panics_on_async_send() {
+        let ctx = BridgeCallContext::stub();
+        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+            let _ = ctx.async_send("_asyncFn", vec![]);
+        }));
+        assert!(result.is_err(), "stub async_send should panic");
+    }
 }

crates/v8-runtime/src/session.rs

@@ -515,8 +515,7 @@ fn session_thread(
 ///
 /// Sync functions block V8 while the host processes the call (applySync/applySyncPromise).
 /// Async functions return a Promise to V8, resolved when the host responds (apply).
-#[cfg(not(test))]
-const SYNC_BRIDGE_FNS: [&str; 31] = [
+pub(crate) const SYNC_BRIDGE_FNS: [&str; 31] = [
     // Console
     "_log",
     "_error",
@@ -555,8 +554,7 @@ const SYNC_BRIDGE_FNS: [&str; 31] = [
     "_childProcessSpawnSync",
 ];
 
-#[cfg(not(test))]
-const ASYNC_BRIDGE_FNS: [&str; 7] = [
+pub(crate) const ASYNC_BRIDGE_FNS: [&str; 7] = [
     // Module loading (async)
     "_dynamicImport",
     // Timer

crates/v8-runtime/src/snapshot.rs

@@ -470,5 +470,140 @@ mod tests {
                 "_testAsync should be a function on restored isolate"
             );
         }
+
+        // --- Part 13: Register stub bridge functions on V8 global ---
+        // Verifies that register_stub_bridge_fns places functions on the global
+        // and that they have the correct typeof without calling them.
+        {
+            use crate::bridge::register_stub_bridge_fns;
+
+            // Use a snapshot-based isolate (consistent with other parts)
+            let bridge_code = "/* stub test */";
+            let blob = create_snapshot(bridge_code).expect("snapshot creation");
+            let mut isolate = create_isolate_from_snapshot(blob, None);
+
+            let scope = &mut v8::HandleScope::new(&mut isolate);
+            let context = v8::Context::new(scope, Default::default());
+            let scope = &mut v8::ContextScope::new(scope, context);
+
+            register_stub_bridge_fns(
+                scope,
+                &["_log", "_error", "_fsReadFile", "_loadPolyfill"],
+                &["_scheduleTimer", "_dynamicImport"],
+            );
+
+            let check = v8::String::new(scope, r#"
+                (function() {
+                    var names = ['_log', '_error', '_fsReadFile', '_loadPolyfill',
+                                 '_scheduleTimer', '_dynamicImport'];
+                    for (var i = 0; i < names.length; i++) {
+                        if (typeof globalThis[names[i]] !== 'function') {
+                            return 'FAIL: ' + names[i] + ' is ' + typeof globalThis[names[i]];
+                        }
+                    }
+                    return 'OK';
+                })()
+            "#).unwrap();
+            let script = v8::Script::compile(scope, check, None).unwrap();
+            let result = script.run(scope).unwrap();
+            assert_eq!(
+                result.to_rust_string_lossy(scope),
+                "OK",
+                "all stub bridge functions should be registered as functions"
+            );
+        }
+
+        // --- Part 14: Bridge IIFE executes against stubs + snapshot creation ---
+        // Verifies that setup-time code can reference stub functions (typeof,
+        // closure wrapping, getter facade) without calling them, and that the
+        // resulting context can be snapshotted.
+        {
+            use crate::bridge::register_stub_bridge_fns;
+            use crate::session::{SYNC_BRIDGE_FNS, ASYNC_BRIDGE_FNS};
+
+            let mut snapshot_isolate = v8::Isolate::snapshot_creator(Some(external_refs()), None);
+            {
+                let scope = &mut v8::HandleScope::new(&mut snapshot_isolate);
+                let context = v8::Context::new(scope, Default::default());
+                let scope = &mut v8::ContextScope::new(scope, context);
+
+                // Register all 38 bridge functions as stubs (no External data)
+                register_stub_bridge_fns(
+                    scope,
+                    &SYNC_BRIDGE_FNS,
+                    &ASYNC_BRIDGE_FNS,
+                );
+
+                // Simulate bridge IIFE: reference all bridge functions, set up
+                // closures and getter facade, but never call any bridge function
+                let iife_code = r#"
+                    (function() {
+                        // Verify bridge functions exist (like ivm-compat shim)
+                        var syncKeys = ['_log', '_error', '_resolveModule', '_loadFile',
+                            '_cryptoRandomFill', '_fsReadFile', '_fsWriteFile',
+                            '_childProcessSpawnStart', '_childProcessSpawnSync'];
+                        var asyncKeys = ['_dynamicImport', '_scheduleTimer',
+                            '_networkFetchRaw', '_networkHttpServerListenRaw'];
+
+                        for (var i = 0; i < syncKeys.length; i++) {
+                            if (typeof globalThis[syncKeys[i]] !== 'function') {
+                                throw new Error('Missing sync: ' + syncKeys[i]);
+                            }
+                        }
+                        for (var i = 0; i < asyncKeys.length; i++) {
+                            if (typeof globalThis[asyncKeys[i]] !== 'function') {
+                                throw new Error('Missing async: ' + asyncKeys[i]);
+                            }
+                        }
+
+                        // Simulate getter-based fs facade (setup only, no calls)
+                        var _fs = {};
+                        Object.defineProperties(_fs, {
+                            readFile:  { get: function() { return globalThis._fsReadFile; },  enumerable: true },
+                            writeFile: { get: function() { return globalThis._fsWriteFile; }, enumerable: true },
+                        });
+                        globalThis._fs = _fs;
+
+                        // Verify getter returns function reference without calling it
+                        if (typeof _fs.readFile !== 'function') {
+                            throw new Error('Getter should return function, got ' + typeof _fs.readFile);
+                        }
+
+                        // Simulate closure wrapping (setup only, no calls)
+                        globalThis.__wrappedLog = function() {
+                            return globalThis._log.apply(null, arguments);
+                        };
+
+                        globalThis.__bridge_setup_complete = true;
+                    })();
+                "#;
+                let source = v8::String::new(scope, iife_code).unwrap();
+                let script = v8::Script::compile(scope, source, None).unwrap();
+                let result = script.run(scope);
+                assert!(
+                    result.is_some(),
+                    "bridge IIFE should execute without error against stub functions"
+                );
+
+                // Verify setup completed
+                let check = v8::String::new(scope, "String(globalThis.__bridge_setup_complete)").unwrap();
+                let script = v8::Script::compile(scope, check, None).unwrap();
+                let val = script.run(scope).unwrap();
+                assert_eq!(
+                    val.to_rust_string_lossy(scope),
+                    "true",
+                    "bridge setup should complete with stub functions"
+                );
+
+                scope.set_default_context(context);
+            }
+
+            let blob = snapshot_isolate.create_blob(v8::FunctionCodeHandling::Keep);
+            assert!(
+                blob.is_some(),
+                "snapshot creation should succeed with stub bridge functions"
+            );
+            assert!(blob.unwrap().len() > 0, "snapshot blob should be non-empty");
+        }
     }
 }