feat: US-065 - Wire post-restore init script through IPC

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

Author: NathanFlurry

crates/v8-runtime/src/execution.rs

@@ -237,6 +237,54 @@ fn run_bridge_cached(
     (0, None)
 }
 
+/// Run a short init script (e.g. post-restore config). Compiles and executes
+/// via v8::Script, returning (exit_code, error) on failure. No code caching.
+pub fn run_init_script(
+    scope: &mut v8::HandleScope,
+    code: &str,
+) -> (i32, Option<ExecutionError>) {
+    if code.is_empty() {
+        return (0, None);
+    }
+    let tc = &mut v8::TryCatch::new(scope);
+    let source = match v8::String::new(tc, code) {
+        Some(s) => s,
+        None => {
+            return (
+                1,
+                Some(ExecutionError {
+                    error_type: "Error".into(),
+                    message: "init script string too large for V8".into(),
+                    stack: String::new(),
+                    code: None,
+                }),
+            );
+        }
+    };
+    let script = match v8::Script::compile(tc, source, None) {
+        Some(s) => s,
+        None => {
+            return match tc.exception() {
+                Some(e) => {
+                    let (c, err) = exception_to_result(tc, e);
+                    (c, Some(err))
+                }
+                None => (1, None),
+            };
+        }
+    };
+    if script.run(tc).is_none() {
+        return match tc.exception() {
+            Some(e) => {
+                let (c, err) = exception_to_result(tc, e);
+                (c, Some(err))
+            }
+            None => (1, None),
+        };
+    }
+    (0, None)
+}
+
 /// Execute user code as a CJS script (mode='exec').
 ///
 /// Runs bridge_code as IIFE first (if non-empty), then compiles and runs user_code

crates/v8-runtime/src/ipc_binary.rs

@@ -60,6 +60,7 @@ pub enum BinaryFrame {
         mode: u8, // 0 = exec, 1 = run
         file_path: String,
         bridge_code: String,
+        post_restore_script: String,
         user_code: String,
     },
     BridgeResponse {
@@ -224,6 +225,7 @@ fn encode_body(buf: &mut Vec<u8>, frame: &BinaryFrame) -> io::Result<()> {
             mode,
             file_path,
             bridge_code,
+            post_restore_script,
             user_code,
         } => {
             buf.push(MSG_EXECUTE);
@@ -235,6 +237,10 @@ fn encode_body(buf: &mut Vec<u8>, frame: &BinaryFrame) -> io::Result<()> {
             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);
+            // post_restore_script length (u32 BE)
+            let prs_bytes = post_restore_script.as_bytes();
+            buf.extend_from_slice(&(prs_bytes.len() as u32).to_be_bytes());
+            buf.extend_from_slice(prs_bytes);
             // user_code (rest of frame)
             buf.extend_from_slice(user_code.as_bytes());
         }
@@ -377,13 +383,16 @@ fn decode_body(buf: &[u8]) -> io::Result<BinaryFrame> {
             let file_path = read_utf8(buf, &mut pos, fp_len)?;
             let bc_len = read_u32(buf, &mut pos)? as usize;
             let bridge_code = read_utf8(buf, &mut pos, bc_len)?;
+            let prs_len = read_u32(buf, &mut pos)? as usize;
+            let post_restore_script = read_utf8(buf, &mut pos, prs_len)?;
             let remaining = buf.len() - pos;
             let user_code = read_utf8(buf, &mut pos, remaining)?;
             Ok(BinaryFrame::Execute {
                 session_id,
                 mode,
                 file_path,
                 bridge_code,
+                post_restore_script,
                 user_code,
             })
         }
@@ -640,6 +649,7 @@ mod tests {
             mode: 0,
             file_path: "".into(),
             bridge_code: "(function(){ /* bridge */ })()".into(),
+            post_restore_script: "".into(),
             user_code: "console.log('hello')".into(),
         });
     }
@@ -651,6 +661,7 @@ mod tests {
             mode: 1,
             file_path: "/app/index.mjs".into(),
             bridge_code: "(function(){ /* bridge */ })()".into(),
+            post_restore_script: "__runtimeApplyConfig({})".into(),
             user_code: "export default 42".into(),
         });
     }
@@ -900,6 +911,7 @@ mod tests {
                 mode: 0,
                 file_path: "".into(),
                 bridge_code: "bridge()".into(),
+                post_restore_script: "".into(),
                 user_code: "1+1".into(),
             },
             BinaryFrame::DestroySession {
@@ -989,6 +1001,7 @@ mod tests {
                 mode: 0,
                 file_path: "".into(),
                 bridge_code: "".into(),
+                post_restore_script: "".into(),
                 user_code: "".into(),
             },
             BinaryFrame::BridgeResponse {
@@ -1085,6 +1098,7 @@ mod tests {
                     mode: 0,
                     file_path: "".into(),
                     bridge_code: "".into(),
+                    post_restore_script: "".into(),
                     user_code: "".into(),
                 },
                 0x05,
@@ -1354,6 +1368,7 @@ mod tests {
             mode: 0,
             file_path: long_path,
             bridge_code: "".into(),
+            post_restore_script: "".into(),
             user_code: "".into(),
         };
         let result = frame_to_bytes(&frame);

crates/v8-runtime/src/session.rs

@@ -309,6 +309,7 @@ fn session_thread(
                     BinaryFrame::Execute {
                         session_id,
                         bridge_code,
+                        post_restore_script,
                         user_code,
                         mode,
                         file_path,
@@ -401,6 +402,30 @@ fn session_thread(
                             );
                         }
 
+                        // Run post-restore init script (config, mutable state reset)
+                        // after bridge fn replacement but before user code
+                        if !post_restore_script.is_empty() {
+                            let scope = &mut v8::HandleScope::new(iso);
+                            let ctx = v8::Local::new(scope, &exec_context);
+                            let scope = &mut v8::ContextScope::new(scope, ctx);
+                            let (prs_code, prs_err) = execution::run_init_script(scope, &post_restore_script);
+                            if prs_code != 0 {
+                                let result_frame = BinaryFrame::ExecutionResult {
+                                    session_id,
+                                    exit_code: prs_code,
+                                    exports: None,
+                                    error: prs_err.map(|e| ExecutionErrorBin {
+                                        error_type: e.error_type,
+                                        message: e.message,
+                                        stack: e.stack,
+                                        code: e.code.unwrap_or_default(),
+                                    }),
+                                };
+                                send_message(&ipc_tx, &result_frame, &mut msg_frame_buf);
+                                continue;
+                            }
+                        }
+
                         // Start timeout guard before execution
                         let mut timeout_guard = match (cpu_time_limit_ms, maybe_abort_tx) {
                             (Some(ms), Some(abort_tx)) => {

packages/secure-exec-core/isolate-runtime/src/common/runtime-globals.d.ts

@@ -114,6 +114,7 @@ declare global {
 				payloadLimitErrorCode?: string;
 		  }) => void)
 		| undefined;
+	var __runtimeResetProcessState: (() => void) | undefined;
 	var __runtimeProcessCwdOverride: unknown;
 	var __runtimeProcessEnvOverride: unknown;
 	var __runtimeStdinData: unknown;

packages/secure-exec-core/src/bridge/process.ts

@@ -113,8 +113,8 @@ function getNowMs(): number {
     : Date.now();
 }
 
-// Start time for uptime calculation
-const _processStartTime = getNowMs();
+// Start time for uptime calculation (mutable for snapshot restore)
+let _processStartTime = getNowMs();
 
 const BUFFER_MAX_LENGTH =
   typeof (BufferPolyfill as unknown as { kMaxLength?: unknown }).kMaxLength ===
@@ -156,6 +156,19 @@ if (
 let _exitCode = 0;
 let _exited = false;
 
+// Expose reset function for snapshot restore — resets mutable state
+// captured in this closure so each restored context starts fresh.
+(globalThis as Record<string, unknown>).__runtimeResetProcessState =
+  function () {
+    _processStartTime =
+      typeof performance !== "undefined" && performance.now
+        ? performance.now()
+        : Date.now();
+    _exitCode = 0;
+    _exited = false;
+    delete (globalThis as Record<string, unknown>).__runtimeResetProcessState;
+  };
+
 /**
  * Thrown by `process.exit()` to unwind the sandbox call stack. The host
  * catches this to extract the exit code without killing the isolate.

packages/secure-exec-node/src/execution-driver.ts

@@ -121,21 +121,20 @@ export function composePostRestoreScript(config: {
 		payloadLimitErrorCode: config.payloadLimitErrorCode,
 	})});`);
 
+	// Reset mutable state from snapshot (no-op on fresh context, resets stale
+	// values on snapshot-restored context)
+	parts.push(`if (typeof globalThis.__runtimeResetProcessState === "function") globalThis.__runtimeResetProcessState();`);
+
 	return parts.join("\n");
 }
 
 /**
- * Compose the default bridge code for snapshot warm-up.
- * Uses timingMitigation='none' and default budget values so the snapshot
- * is ready for the most common session configuration.
+ * Compose the bridge code for snapshot warm-up.
+ * Returns only the static IIFE — the post-restore script is sent
+ * separately per-execution so the snapshot is config-independent.
  */
 export function composeBridgeCodeForWarmup(): string {
-	return composeStaticBridgeCode() + "\n" + composePostRestoreScript({
-		timingMitigation: "off",
-		frozenTimeMs: 0,
-		payloadLimitBytes: DEFAULT_ISOLATE_JSON_PAYLOAD_BYTES,
-		payloadLimitErrorCode: PAYLOAD_LIMIT_ERROR_CODE,
-	});
+	return composeStaticBridgeCode();
 }
 
 const MAX_ERROR_MESSAGE_CHARS = 8192;
@@ -274,12 +273,17 @@ export class NodeExecutionDriver implements RuntimeDriver {
 		});
 	}
 
-	/** Compose the full bridge code: static IIFE + per-execution post-restore script. */
-	private composeBridgeCode(
+	/** Compose the static bridge IIFE (no per-session config). */
+	private composeBridgeCode(): string {
+		return composeStaticBridgeCode();
+	}
+
+	/** Compose the per-execution post-restore script. */
+	private composePostRestore(
 		timingMitigation: TimingMitigation,
 		frozenTimeMs: number,
 	): string {
-		return composeStaticBridgeCode() + "\n" + composePostRestoreScript({
+		return composePostRestoreScript({
 			timingMitigation,
 			frozenTimeMs,
 			maxTimers: this.deps.maxTimers,
@@ -325,8 +329,9 @@ export class NodeExecutionDriver implements RuntimeDriver {
 			},
 		});
 
-		// Compose bridge code
-		const bridgeCode = this.composeBridgeCode(timingMitigation, frozenTimeMs);
+		// Compose bridge code and post-restore script (sent separately over IPC)
+		const bridgeCode = this.composeBridgeCode();
+		const postRestoreScript = this.composePostRestore(timingMitigation, frozenTimeMs);
 
 		// Transform user code (dynamic import → __dynamicImport)
 		const userCode = transformDynamicImport(options.code);
@@ -370,6 +375,7 @@ export class NodeExecutionDriver implements RuntimeDriver {
 			// Execute via V8 session
 			const result: V8ExecutionResult = await session.execute({
 				bridgeCode,
+				postRestoreScript,
 				userCode: fullUserCode,
 				mode: options.mode,
 				filePath: options.filePath,

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

@@ -63,6 +63,7 @@ export type BinaryFrame =
 			mode: number;
 			filePath: string;
 			bridgeCode: string;
+			postRestoreScript: string;
 			userCode: string;
 	  }
 	| {
@@ -166,13 +167,18 @@ export function decodeFrame(buf: Buffer): BinaryFrame {
 			pos += 4;
 			const bridgeCode = buf.toString("utf8", pos, pos + bcLen);
 			pos += bcLen;
+			const prsLen = buf.readUInt32BE(pos);
+			pos += 4;
+			const postRestoreScript = buf.toString("utf8", pos, pos + prsLen);
+			pos += prsLen;
 			const userCode = buf.toString("utf8", pos);
 			return {
 				type: "Execute",
 				sessionId,
 				mode,
 				filePath,
 				bridgeCode,
+				postRestoreScript,
 				userCode,
 			};
 		}
@@ -325,6 +331,12 @@ function encodeBody(frame: BinaryFrame): Buffer {
 			bcLen.writeUInt32BE(bcBuf.length, 0);
 			parts.push(bcLen);
 			parts.push(bcBuf);
+			// post_restore_script (u32 BE length prefix)
+			const prsBuf = Buffer.from(frame.postRestoreScript, "utf8");
+			const prsLen = Buffer.alloc(4);
+			prsLen.writeUInt32BE(prsBuf.length, 0);
+			parts.push(prsLen);
+			parts.push(prsBuf);
 			// user_code (rest of frame)
 			parts.push(Buffer.from(frame.userCode, "utf8"));
 			break;

packages/secure-exec-v8/src/runtime.ts

@@ -389,6 +389,7 @@ export async function createV8Runtime(
 						type: "Execute",
 						sessionId,
 						bridgeCode: sendBridgeCode ? execOptions.bridgeCode : "",
+						postRestoreScript: execOptions.postRestoreScript ?? "",
 						userCode: execOptions.userCode,
 						mode: execOptions.mode === "exec" ? 0 : 1,
 						filePath: execOptions.filePath ?? "",

packages/secure-exec-v8/src/session.ts

@@ -23,6 +23,8 @@ export interface V8ExecutionResult {
 export interface V8ExecutionOptions {
 	/** Bridge bundle IIFE to execute before user code. */
 	bridgeCode: string;
+	/** Post-restore config script — runs after bridge replacement, before user code. */
+	postRestoreScript?: string;
 	/** User code to execute. */
 	userCode: string;
 	/** Execution mode: 'exec' for CJS script, 'run' for ES module. */

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

@@ -73,6 +73,7 @@ describe("Host → Rust messages", () => {
 			mode: 0,
 			filePath: "",
 			bridgeCode: "(function(){ /* bridge */ })()",
+			postRestoreScript: "",
 			userCode: "console.log('hello')",
 		});
 	});
@@ -84,6 +85,7 @@ describe("Host → Rust messages", () => {
 			mode: 1,
 			filePath: "/app/index.mjs",
 			bridgeCode: "(function(){ /* bridge */ })()",
+			postRestoreScript: "",
 			userCode: "export default 42",
 		});
 	});
@@ -315,6 +317,7 @@ describe("framing validation", () => {
 				mode: 0,
 				filePath: "",
 				bridgeCode: "bridge()",
+				postRestoreScript: "",
 				userCode: "1+1",
 			},
 			{ type: "DestroySession", sessionId: "a" },
@@ -379,6 +382,7 @@ describe("session_id extraction", () => {
 					mode: 0,
 					filePath: "",
 					bridgeCode: "",
+					postRestoreScript: "",
 					userCode: "",
 				},
 				"sess-exec",
@@ -470,6 +474,7 @@ describe("wire format interop", () => {
 					mode: 0,
 					filePath: "",
 					bridgeCode: "",
+					postRestoreScript: "",
 					userCode: "",
 				},
 				0x05,