feat: US-056 - Add eager snapshot warm-up on module load

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

Author: NathanFlurry

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

@@ -9,7 +9,9 @@ let sharedV8RuntimePromise: Promise<V8Runtime> | null = null;
 async function getSharedV8Runtime(): Promise<V8Runtime> {
 	if (sharedV8Runtime) return sharedV8Runtime;
 	if (!sharedV8RuntimePromise) {
-		sharedV8RuntimePromise = createV8Runtime().then((r) => {
+		sharedV8RuntimePromise = createV8Runtime({
+			warmupBridgeCode: composeBridgeCodeForWarmup(),
+		}).then((r) => {
 			sharedV8Runtime = r;
 			return r;
 		});
@@ -34,6 +36,46 @@ import { createProcessConfigForExecution } from "./bridge-setup.js";
 
 export { NodeExecutionDriverOptions };
 
+/**
+ * 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.
+ */
+export function composeBridgeCodeForWarmup(): string {
+	const parts: string[] = [];
+
+	parts.push(getIvmCompatShimSource());
+
+	parts.push(`globalThis._maxTimers = ${DEFAULT_MAX_TIMERS};`);
+	parts.push(`globalThis._maxHandles = ${DEFAULT_MAX_HANDLES};`);
+	parts.push(`globalThis.__runtimeBridgeSetupConfig = ${JSON.stringify({
+		initialCwd: DEFAULT_SANDBOX_CWD,
+		jsonPayloadLimitBytes: DEFAULT_ISOLATE_JSON_PAYLOAD_BYTES,
+		payloadLimitErrorCode: PAYLOAD_LIMIT_ERROR_CODE,
+	})};`);
+
+	parts.push(getIsolateRuntimeSource("globalExposureHelpers"));
+	parts.push(getInitialBridgeGlobalsSetupCode());
+	parts.push(getConsoleSetupCode());
+	parts.push(getIsolateRuntimeSource("setupFsFacade"));
+	parts.push(getRawBridgeCode());
+	parts.push(getBridgeAttachCode());
+
+	// Default: no timing mitigation
+	parts.push(getIsolateRuntimeSource("applyTimingMitigationOff"));
+
+	parts.push(getRequireSetupCode());
+	parts.push(getIsolateRuntimeSource("initCommonjsModuleGlobals"));
+
+	parts.push(`globalThis.__runtimeCustomGlobalPolicy = ${JSON.stringify({
+		hardenedGlobals: HARDENED_NODE_CUSTOM_GLOBALS,
+		mutableGlobals: MUTABLE_NODE_CUSTOM_GLOBALS,
+	})};`);
+	parts.push(getIsolateRuntimeSource("applyCustomGlobalPolicy"));
+
+	return parts.join("\n");
+}
+
 const MAX_ERROR_MESSAGE_CHARS = 8192;
 
 function boundErrorMessage(message: string): string {

packages/secure-exec-node/src/index.ts

@@ -26,7 +26,7 @@ export {
 } from "./polyfills.js";
 
 // Node execution driver
-export { NodeExecutionDriver } from "./execution-driver.js";
+export { NodeExecutionDriver, composeBridgeCodeForWarmup } from "./execution-driver.js";
 export type { NodeExecutionDriverOptions } from "./isolate-bootstrap.js";
 
 // Node system driver

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

@@ -31,6 +31,8 @@ export interface V8RuntimeOptions {
 	binaryPath?: string;
 	/** Maximum concurrent sessions. Passed via SECURE_EXEC_V8_MAX_SESSIONS. */
 	maxSessions?: number;
+	/** Bridge code to pre-warm the snapshot cache with (fire-and-forget). Skipped if SECURE_EXEC_NO_SNAPSHOT_WARMUP=1. */
+	warmupBridgeCode?: string;
 }
 
 /** Manages the Rust V8 child process and session lifecycle. */
@@ -178,6 +180,14 @@ export async function createV8Runtime(
 	try {
 		await ipcClient.connect();
 		ipcClient.authenticate(authToken);
+
+		// Send warm-up snapshot request (fire-and-forget)
+		if (options?.warmupBridgeCode && process.env.SECURE_EXEC_NO_SNAPSHOT_WARMUP !== "1") {
+			ipcClient.send({
+				type: "WarmSnapshot",
+				bridgeCode: options.warmupBridgeCode,
+			});
+		}
 	} catch (err) {
 		// Connection failed — kill child and surface error
 		child.kill("SIGTERM");