feat: US-054 - Add WarmSnapshot IPC message type

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

Author: NathanFlurry

crates/v8-runtime/src/ipc_binary.rs

@@ -24,6 +24,7 @@ const MSG_EXECUTE: u8 = 0x05;
 const MSG_BRIDGE_RESPONSE: u8 = 0x06;
 const MSG_STREAM_EVENT: u8 = 0x07;
 const MSG_TERMINATE_EXECUTION: u8 = 0x08;
+const MSG_WARM_SNAPSHOT: u8 = 0x09;
 
 // Rust → Host message type codes
 const MSG_BRIDGE_CALL: u8 = 0x81;
@@ -75,6 +76,9 @@ pub enum BinaryFrame {
     TerminateExecution {
         session_id: String,
     },
+    WarmSnapshot {
+        bridge_code: String,
+    },
 
     // Rust → Host
     BridgeCall {
@@ -171,7 +175,7 @@ pub fn extract_session_id(raw: &[u8]) -> io::Result<Option<&str>> {
         return Err(io::Error::new(io::ErrorKind::InvalidData, "frame too short"));
     }
     let msg_type = raw[0];
-    if msg_type == MSG_AUTHENTICATE {
+    if msg_type == MSG_AUTHENTICATE || msg_type == MSG_WARM_SNAPSHOT {
         return Ok(None);
     }
     let sid_len = raw[1] as usize;
@@ -264,6 +268,13 @@ fn encode_body(buf: &mut Vec<u8>, frame: &BinaryFrame) {
             buf.push(MSG_TERMINATE_EXECUTION);
             write_session_id(buf, session_id);
         }
+        BinaryFrame::WarmSnapshot { bridge_code } => {
+            buf.push(MSG_WARM_SNAPSHOT);
+            buf.push(0); // no session_id
+            let bc_bytes = bridge_code.as_bytes();
+            buf.extend_from_slice(&(bc_bytes.len() as u32).to_be_bytes());
+            buf.extend_from_slice(bc_bytes);
+        }
         BinaryFrame::BridgeCall {
             session_id,
             call_id,
@@ -405,6 +416,11 @@ fn decode_body(buf: &[u8]) -> io::Result<BinaryFrame> {
             })
         }
         MSG_TERMINATE_EXECUTION => Ok(BinaryFrame::TerminateExecution { session_id }),
+        MSG_WARM_SNAPSHOT => {
+            let bc_len = read_u32(buf, &mut pos)? as usize;
+            let bridge_code = read_utf8(buf, &mut pos, bc_len)?;
+            Ok(BinaryFrame::WarmSnapshot { bridge_code })
+        }
         MSG_BRIDGE_CALL => {
             let call_id = read_u32(buf, &mut pos)?;
             let m_len = read_u16(buf, &mut pos)? as usize;
@@ -760,6 +776,41 @@ mod tests {
         });
     }
 
+    // -- WarmSnapshot --
+
+    #[test]
+    fn roundtrip_warm_snapshot() {
+        roundtrip(&BinaryFrame::WarmSnapshot {
+            bridge_code: "(function(){ /* bridge IIFE */ })()".into(),
+        });
+    }
+
+    #[test]
+    fn roundtrip_warm_snapshot_empty_bridge_code() {
+        roundtrip(&BinaryFrame::WarmSnapshot {
+            bridge_code: "".into(),
+        });
+    }
+
+    #[test]
+    fn roundtrip_warm_snapshot_large_bridge_code() {
+        roundtrip(&BinaryFrame::WarmSnapshot {
+            bridge_code: "x".repeat(100_000),
+        });
+    }
+
+    #[test]
+    fn extract_session_id_warm_snapshot_returns_none() {
+        let frame = BinaryFrame::WarmSnapshot {
+            bridge_code: "bridge()".into(),
+        };
+        let mut buf = Vec::new();
+        write_frame(&mut buf, &frame).expect("write");
+        let raw = &buf[4..];
+        let result = extract_session_id(raw).expect("extract");
+        assert_eq!(result, None);
+    }
+
     // -- Edge cases --
 
     #[test]
@@ -1042,6 +1093,12 @@ mod tests {
                 },
                 0x08,
             ),
+            (
+                BinaryFrame::WarmSnapshot {
+                    bridge_code: "bridge()".into(),
+                },
+                0x09,
+            ),
             (
                 BinaryFrame::BridgeCall {
                     session_id: "s".into(),

packages/secure-exec-v8/src/ipc-binary.ts

@@ -25,6 +25,7 @@ const MSG_EXECUTE = 0x05;
 const MSG_BRIDGE_RESPONSE = 0x06;
 const MSG_STREAM_EVENT = 0x07;
 const MSG_TERMINATE_EXECUTION = 0x08;
+const MSG_WARM_SNAPSHOT = 0x09;
 
 // Rust → Host message type codes
 const MSG_BRIDGE_CALL = 0x81;
@@ -78,6 +79,7 @@ export type BinaryFrame =
 			payload: Buffer;
 	  }
 	| { type: "TerminateExecution"; sessionId: string }
+	| { type: "WarmSnapshot"; bridgeCode: string }
 	// Rust → Host
 	| {
 			type: "BridgeCall";
@@ -191,6 +193,12 @@ export function decodeFrame(buf: Buffer): BinaryFrame {
 		}
 		case MSG_TERMINATE_EXECUTION:
 			return { type: "TerminateExecution", sessionId };
+		case MSG_WARM_SNAPSHOT: {
+			const bcLen = buf.readUInt32BE(pos);
+			pos += 4;
+			const bridgeCode = buf.toString("utf8", pos, pos + bcLen);
+			return { type: "WarmSnapshot", bridgeCode };
+		}
 		case MSG_BRIDGE_CALL: {
 			const callId = buf.readUInt32BE(pos);
 			pos += 4;
@@ -255,7 +263,7 @@ export function extractSessionId(raw: Buffer): string | null {
 		throw new Error("Frame too short");
 	}
 	const msgType = raw[0];
-	if (msgType === MSG_AUTHENTICATE) {
+	if (msgType === MSG_AUTHENTICATE || msgType === MSG_WARM_SNAPSHOT) {
 		return null;
 	}
 	const sidLen = raw[1];
@@ -342,6 +350,15 @@ function encodeBody(frame: BinaryFrame): Buffer {
 			parts.push(encodeSessionId(frame.sessionId));
 			break;
 		}
+		case "WarmSnapshot": {
+			parts.push(Buffer.from([MSG_WARM_SNAPSHOT, 0])); // no session_id
+			const bcBuf = Buffer.from(frame.bridgeCode, "utf8");
+			const bcLen = Buffer.alloc(4);
+			bcLen.writeUInt32BE(bcBuf.length, 0);
+			parts.push(bcLen);
+			parts.push(bcBuf);
+			break;
+		}
 		case "BridgeCall": {
 			parts.push(Buffer.from([MSG_BRIDGE_CALL]));
 			parts.push(encodeSessionId(frame.sessionId));

packages/secure-exec-v8/test/ipc-binary.test.ts

@@ -119,6 +119,21 @@ describe("Host → Rust messages", () => {
 	it("round-trips TerminateExecution", () => {
 		roundtrip({ type: "TerminateExecution", sessionId: "sess-6" });
 	});
+
+	it("round-trips WarmSnapshot", () => {
+		roundtrip({
+			type: "WarmSnapshot",
+			bridgeCode: "(function(){ /* bridge IIFE */ })()",
+		});
+	});
+
+	it("round-trips WarmSnapshot with empty bridge code", () => {
+		roundtrip({ type: "WarmSnapshot", bridgeCode: "" });
+	});
+
+	it("round-trips WarmSnapshot with large bridge code", () => {
+		roundtrip({ type: "WarmSnapshot", bridgeCode: "x".repeat(100_000) });
+	});
 });
 
 // -- Rust → Host message types --
@@ -400,6 +415,16 @@ describe("session_id extraction", () => {
 		}
 	});
 
+	it("returns null for WarmSnapshot", () => {
+		const frame: BinaryFrame = {
+			type: "WarmSnapshot",
+			bridgeCode: "bridge()",
+		};
+		const encoded = encodeFrame(frame);
+		const raw = encoded.subarray(4);
+		expect(extractSessionId(raw)).toBeNull();
+	});
+
 	it("returns null for Authenticate", () => {
 		const frame: BinaryFrame = {
 			type: "Authenticate",
@@ -468,6 +493,7 @@ describe("wire format interop", () => {
 				0x07,
 			],
 			[{ type: "TerminateExecution", sessionId: "s" }, 0x08],
+			[{ type: "WarmSnapshot", bridgeCode: "bridge()" }, 0x09],
 			[
 				{
 					type: "BridgeCall",
@@ -559,6 +585,20 @@ describe("wire format interop", () => {
 		); // payload
 	});
 
+	it("WarmSnapshot wire format matches Rust layout", () => {
+		const frame: BinaryFrame = {
+			type: "WarmSnapshot",
+			bridgeCode: "hi",
+		};
+		const encoded = encodeFrame(frame);
+		const body = encoded.subarray(4);
+		expect(body[0]).toBe(0x09); // msg_type
+		expect(body[1]).toBe(0); // sid_len = 0
+		expect(body.readUInt32BE(2)).toBe(2); // bridge_code_len
+		expect(body.toString("utf8", 6, 8)).toBe("hi"); // bridge_code
+		expect(body.length).toBe(8); // total body: 1+1+4+2
+	});
+
 	it("ExecutionResult flags and error layout match Rust", () => {
 		const frame: BinaryFrame = {
 			type: "ExecutionResult",