refactor: split runtime driver from execution factory

NathanFlurry · NathanFlurry · commit 9cb32ac34914 · 2026-03-01T19:08:20.000-08:00
diff --git a/docs-internal/arch/overview.md b/docs-internal/arch/overview.md
@@ -1,8 +1,8 @@
 # Architecture Overview
 
 ```
-NodeRuntime  →  RuntimeDriver  →  NodeExecutionDriver
-  (API)          (config)           (isolated-vm engine)
+NodeRuntime  →  RuntimeDriver + RuntimeExecutionDriverFactory  →  NodeExecutionDriver
+  (API)          (capability/config + execution wiring)           (isolated-vm engine)
 ```
 
 ## NodeRuntime
@@ -14,6 +14,9 @@ Public API. Thin facade — delegates everything to the execution driver.
 - `run(code)` — execute as module, get exports back
 - `exec(code)` — execute as script, get exit code + stdout/stderr
 - `dispose()` / `terminate()`
+- Requires both:
+  - `driver` for runtime capabilities/config
+  - `executionFactory` for execution-driver construction
 
 ## RuntimeDriver
 
@@ -25,7 +28,12 @@ Config object that bundles what the sandbox can access. Deny-by-default.
 - `network` — fetch, DNS, HTTP
 - `commandExecutor` — child processes
 - `permissions` — per-adapter allow/deny checks
-- `runtimeHooks` — factories for isolate + execution driver
+
+## RuntimeExecutionDriverFactory
+
+Factory abstraction for constructing execution drivers from normalized runtime options.
+
+- `createExecutionDriver(options)` — returns a `RuntimeExecutionDriver`
 
 ### createNodeDriver()
 
@@ -36,6 +44,15 @@ Factory that builds a `RuntimeDriver` with Node-native adapters.
 - Wraps filesystem in `ModuleAccessFileSystem` (read-only `node_modules` overlay)
 - Optionally wires up network and command executor
 
+### createNodeExecutionFactory()
+
+`src/node/driver.ts`
+
+Factory that builds a Node-backed `RuntimeExecutionDriverFactory`.
+
+- Constructs `NodeExecutionDriver` instances
+- Owns optional Node-specific isolate creation hook
+
 ## NodeExecutionDriver
 
 `src/node/execution-driver.ts`
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
@@ -11,9 +11,12 @@ description: Get secure-exec running from TypeScript in a few minutes.
   </Step>
   <Step title="Execute code">
     ```ts
-    import { NodeRuntime, createNodeDriver } from "secure-exec";
+    import { NodeRuntime, createNodeDriver, createNodeExecutionFactory } from "secure-exec";
 
-    const proc = new NodeRuntime({ driver: createNodeDriver({}) });
+    const proc = new NodeRuntime({
+      driver: createNodeDriver({}),
+      executionFactory: createNodeExecutionFactory(),
+    });
     const logs: string[] = [];
     const result = await proc.exec("console.log('hello from secure-exec')", {
       onStdio: (event) => {
diff --git a/examples/hono/loader/src/index.ts b/examples/hono/loader/src/index.ts
@@ -8,6 +8,7 @@ import {
   NodeFileSystem,
   NodeRuntime,
   createNodeDriver,
+  createNodeExecutionFactory,
 } from "../../../../packages/secure-exec/src/index.ts";
 import {
   LOOPBACK_HOST,
@@ -33,6 +34,7 @@ function createProcess(runnerRoot: string, runnerEntry: string): NodeRuntime {
 
   return new NodeRuntime({
     driver,
+    executionFactory: createNodeExecutionFactory(),
   });
 }
 
diff --git a/examples/just-bash/src/index.ts b/examples/just-bash/src/index.ts
@@ -3,6 +3,7 @@ import {
   allowAll,
   NodeRuntime,
   createNodeDriver,
+  createNodeExecutionFactory,
   type CommandExecutor,
   type SpawnedProcess,
   type VirtualFileSystem,
@@ -92,7 +93,10 @@ async function main(): Promise<void> {
     permissions: allowAll,
   });
 
-  const proc = new NodeRuntime({ driver });
+  const proc = new NodeRuntime({
+    driver,
+    executionFactory: createNodeExecutionFactory(),
+  });
   const result = await proc.exec(`
     const { execSync } = require('child_process');
     const output = execSync('echo hello from bash');
diff --git a/openspec/changes/archive/2026-03-02-split-runtime-driver-and-execution-factory/.openspec.yaml b/openspec/changes/archive/2026-03-02-split-runtime-driver-and-execution-factory/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-02
diff --git a/openspec/changes/archive/2026-03-02-split-runtime-driver-and-execution-factory/design.md b/openspec/changes/archive/2026-03-02-split-runtime-driver-and-execution-factory/design.md
@@ -0,0 +1,45 @@
+## Context
+
+`RuntimeDriver` currently carries both capability configuration (filesystem/network/child-process/permissions/runtime config) and execution-construction hooks (`runtimeHooks`). This mixes data ownership with engine-construction concerns and makes the generic driver type depend on Node-specific execution wiring.
+
+The goal is to preserve runtime behavior while clarifying boundaries: capability data stays on the driver, and execution construction moves to a separate factory contract.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Separate capability/config ownership from execution-engine construction.
+- Keep `runtime.process` and `runtime.os` sourced from the driver and injected into execution.
+- Preserve deny-by-default semantics and existing run/exec behavior.
+- Provide a clean extension point for non-Node execution engines without hook leakage.
+
+**Non-Goals:**
+- Reworking module loading/bridge semantics.
+- Changing permission policy behavior.
+- Restoring browser runtime support in this change.
+
+## Decisions
+
+1. Introduce explicit execution factory contract.
+- Decision: Add a dedicated runtime execution factory/provider type and remove `runtimeHooks` from `RuntimeDriver`.
+- Rationale: keeps `RuntimeDriver` as pure capability/config surface and removes implicit, optional hook coupling.
+- Alternative considered: keep `runtimeHooks` but make fields required. Rejected because it still blends concerns and keeps generic driver tied to execution internals.
+
+2. Update `NodeRuntime` constructor to accept both capability driver and execution factory.
+- Decision: `NodeRuntime` requires explicit factory wiring at construction time.
+- Rationale: dependency is explicit at API boundary and independent of driver data shape.
+- Alternative considered: global/default factory fallback. Rejected because hidden defaults reduce clarity and complicate multi-runtime composition.
+
+3. Keep runtime config injection path unchanged in intent.
+- Decision: `process`/`os` config remains on driver and is normalized by `NodeRuntime` before creating execution driver.
+- Rationale: preserves current ownership expectations and avoids duplicating runtime config across surfaces.
+- Alternative considered: move runtime config into factory options only. Rejected because driver is the canonical capability/config bundle.
+
+4. Keep Node-owned heavy lifting in Node factory/driver modules.
+- Decision: Node-specific isolate wiring and execution driver construction stays in Node implementation modules, not generic runtime types.
+- Rationale: aligns with driver-owned specialization and reduces generic runtime coupling.
+
+## Risks / Trade-offs
+
+- [Breaking API surface] Constructor/type signatures change for hosts creating `NodeRuntime` directly. → Mitigation: update exports/types in one change and cover with type tests.
+- [Migration confusion] Existing code may still expect `driver.runtimeHooks`. → Mitigation: remove hook references in runtime/docs and update Node factory helpers to provide the new execution factory directly.
+- [Behavior drift risk] Refactor could accidentally alter deny-by-default behavior. → Mitigation: run targeted permissions/runtime tests and preserve adapter wrapping/stubs paths.
diff --git a/openspec/changes/archive/2026-03-02-split-runtime-driver-and-execution-factory/proposal.md b/openspec/changes/archive/2026-03-02-split-runtime-driver-and-execution-factory/proposal.md
@@ -0,0 +1,34 @@
+## Why
+
+`RuntimeDriver` currently mixes two responsibilities: capability/config data and execution-engine construction via `runtimeHooks`. This coupling leaks Node execution concerns into generic driver typing and makes alternate runtimes harder to add or reason about.
+
+## What Changes
+
+- Remove execution-construction hooks from `RuntimeDriver`.
+- Introduce a separate execution-factory contract for constructing `RuntimeExecutionDriver` instances.
+- Update `NodeRuntime` construction to require both a capability driver and an execution factory/provider.
+- Keep runtime/process/os config sourced from the driver and injected into execution construction.
+- Preserve deny-by-default behavior for omitted adapters/permissions.
+- Update Node driver assembly so Node-specific execution construction is owned by Node factory code rather than generic driver hooks.
+- Update internal architecture docs to reflect the split.
+
+## Capabilities
+
+### New Capabilities
+- None.
+
+### Modified Capabilities
+- `node-runtime`: Runtime construction contract changes from hook-based execution creation on `RuntimeDriver` to explicit execution-factory wiring while preserving runtime behavior.
+
+## Impact
+
+- Affected code:
+  - `packages/secure-exec/src/runtime-driver.ts`
+  - `packages/secure-exec/src/index.ts`
+  - `packages/secure-exec/src/node/driver.ts`
+  - `packages/secure-exec/src/node/execution-driver.ts`
+  - related tests and docs
+- API impact:
+  - **BREAKING**: `NodeRuntime` constructor options and runtime-driver typing change.
+- Dependencies:
+  - No new external dependencies expected.
diff --git a/openspec/changes/archive/2026-03-02-split-runtime-driver-and-execution-factory/specs/node-runtime/spec.md b/openspec/changes/archive/2026-03-02-split-runtime-driver-and-execution-factory/specs/node-runtime/spec.md
@@ -0,0 +1,20 @@
+## MODIFIED Requirements
+
+### Requirement: Driver-Based Capability Composition
+Runtime capabilities SHALL be composed through host-provided drivers so filesystem, network, and child-process behavior are controlled by configured adapters rather than hardcoded runtime behavior. `NodeRuntime` construction SHALL require both a capability driver and an execution factory.
+
+#### Scenario: Node runtime uses configured adapters with explicit execution factory
+- **WHEN** `NodeRuntime` is created with a driver that defines filesystem, network, and command-execution adapters and with an execution factory
+- **THEN** sandboxed operations MUST route through those adapters for capability access and execution MUST be created through the provided factory
+
+#### Scenario: Missing permissions deny capability access by default
+- **WHEN** a driver is configured without explicit permission allowance for a capability domain
+- **THEN** operations in that capability domain MUST be denied by default
+
+#### Scenario: Omitted capability remains unavailable
+- **WHEN** a capability adapter is omitted from runtime configuration
+- **THEN** corresponding sandbox operations MUST be unavailable or denied by the runtime contract
+
+#### Scenario: Runtime process/os config remains driver-owned
+- **WHEN** a caller provides runtime `process` and `os` configuration on the driver
+- **THEN** `NodeRuntime` MUST source and inject that configuration into execution creation
diff --git a/openspec/changes/archive/2026-03-02-split-runtime-driver-and-execution-factory/tasks.md b/openspec/changes/archive/2026-03-02-split-runtime-driver-and-execution-factory/tasks.md
@@ -0,0 +1,17 @@
+## 1. Type and API Surface Split
+
+- [x] 1.1 Remove `runtimeHooks` from `RuntimeDriver` and define a dedicated runtime execution factory/provider contract in `runtime-driver.ts`.
+- [x] 1.2 Update `NodeRuntimeOptions` and `NodeRuntime` construction to require both `driver` (capabilities/config) and execution factory/provider.
+- [x] 1.3 Update exports and re-exported types so consumers can use the new contracts without importing internal paths.
+
+## 2. Node Implementation Wiring
+
+- [x] 2.1 Refactor Node driver assembly to return pure capability/config driver data and separate Node execution factory wiring.
+- [x] 2.2 Update Node execution-driver options/types to consume the new construction contract instead of `driver.runtimeHooks`.
+- [x] 2.3 Remove obsolete hook-based wiring and keep runtime process/os config injection behavior unchanged.
+
+## 3. Validation and Docs
+
+- [x] 3.1 Update tests to cover the new constructor/factory wiring and preserve deny-by-default semantics.
+- [x] 3.2 Update architecture documentation to describe the split between capability driver and execution factory.
+- [x] 3.3 Run targeted typecheck/tests and mark tasks complete.
diff --git a/openspec/specs/node-runtime/spec.md b/openspec/specs/node-runtime/spec.md
@@ -31,11 +31,11 @@ The project SHALL provide a stable Node sandbox execution interface, with `NodeR
 - **THEN** the result's `exports` field MUST be an object containing both the `default` property and all named export properties
 
 ### Requirement: Driver-Based Capability Composition
-Runtime capabilities SHALL be composed through host-provided drivers so filesystem, network, and child-process behavior are controlled by configured adapters rather than hardcoded runtime behavior. `NodeRuntime` construction SHALL require a driver.
+Runtime capabilities SHALL be composed through host-provided drivers so filesystem, network, and child-process behavior are controlled by configured adapters rather than hardcoded runtime behavior. `NodeRuntime` construction SHALL require both a capability driver and an execution factory.
 
-#### Scenario: Node process uses configured adapters
-- **WHEN** `NodeRuntime` is created with a driver that defines filesystem, network, and command-execution adapters
-- **THEN** sandboxed operations MUST route through those adapters for capability access
+#### Scenario: Node runtime uses configured adapters with explicit execution factory
+- **WHEN** `NodeRuntime` is created with a driver that defines filesystem, network, and command-execution adapters and with an execution factory
+- **THEN** sandboxed operations MUST route through those adapters for capability access and execution MUST be created through the provided factory
 
 #### Scenario: Missing permissions deny capability access by default
 - **WHEN** a driver is configured without explicit permission allowance for a capability domain
@@ -45,6 +45,10 @@ Runtime capabilities SHALL be composed through host-provided drivers so filesyst
 - **WHEN** a capability adapter is omitted from runtime configuration
 - **THEN** corresponding sandbox operations MUST be unavailable or denied by the runtime contract
 
+#### Scenario: Runtime process/os config remains driver-owned
+- **WHEN** a caller provides runtime `process` and `os` configuration on the driver
+- **THEN** `NodeRuntime` MUST source and inject that configuration into execution creation
+
 ### Requirement: Active Handle Completion for Async Operations
 The Node runtime SHALL wait for tracked active handles before finalizing execution results so callback-driven asynchronous work can complete.
 
diff --git a/packages/secure-exec/src/index.ts b/packages/secure-exec/src/index.ts
@@ -2,6 +2,7 @@ import { createNetworkStub, filterEnv } from "./shared/permissions.js";
 import type {
 	NetworkAdapter,
 	RuntimeExecutionDriver,
+	RuntimeExecutionDriverFactory,
 	RuntimeDriver,
 } from "./types.js";
 import type {
@@ -17,6 +18,7 @@ export type {
 	CommandExecutor,
 	NetworkAdapter,
 	Permissions,
+	RuntimeExecutionDriverFactory,
 	RuntimeDriver,
 	VirtualFileSystem,
 } from "./types.js";
@@ -35,10 +37,11 @@ export type {
 export {
 	createDefaultNetworkAdapter,
 	createNodeDriver,
+	createNodeExecutionFactory,
 	NodeExecutionDriver,
 	NodeFileSystem,
 } from "./node/driver.js";
-export type { ModuleAccessOptions } from "./node/driver.js";
+export type { ModuleAccessOptions, NodeExecutionFactoryOptions } from "./node/driver.js";
 export { createInMemoryFileSystem } from "./shared/in-memory-fs.js";
 export {
 	allowAll,
@@ -54,6 +57,7 @@ const DEFAULT_SANDBOX_TMPDIR = "/tmp";
 
 export interface NodeRuntimeOptions {
 	driver: RuntimeDriver;
+	executionFactory: RuntimeExecutionDriverFactory;
 	memoryLimit?: number;
 	cpuTimeLimitMs?: number;
 	timingMitigation?: TimingMitigation;
@@ -77,11 +81,7 @@ export class NodeRuntime {
 	private readonly executionDriver: UnsafeRuntimeExecutionDriver;
 
 	constructor(options: NodeRuntimeOptions) {
-		const { driver } = options;
-		const createExecutionDriver = driver.runtimeHooks?.createExecutionDriver;
-		if (!createExecutionDriver) {
-			throw new Error("NodeRuntime requires driver.runtimeHooks.createExecutionDriver");
-		}
+		const { driver, executionFactory } = options;
 
 		const processConfig = {
 			...(driver.runtime.process ?? {}),
@@ -95,7 +95,7 @@ export class NodeRuntime {
 		osConfig.homedir ??= DEFAULT_SANDBOX_HOME;
 		osConfig.tmpdir ??= DEFAULT_SANDBOX_TMPDIR;
 
-		this.executionDriver = createExecutionDriver({
+		this.executionDriver = executionFactory.createExecutionDriver({
 			driver,
 			runtime: {
 				process: processConfig,
diff --git a/packages/secure-exec/src/node/driver.ts b/packages/secure-exec/src/node/driver.ts
@@ -9,7 +9,6 @@ import {
 	filterEnv,
 } from "../shared/permissions.js";
 import { ModuleAccessFileSystem } from "./module-access.js";
-import { createIsolate } from "../isolate.js";
 import { NodeExecutionDriver } from "./execution-driver.js";
 import type {
 	OSConfig,
@@ -19,6 +18,7 @@ import type {
 	CommandExecutor,
 	NetworkAdapter,
 	Permissions,
+	RuntimeExecutionDriverFactory,
 	RuntimeDriver,
 	VirtualFileSystem,
 } from "../types.js";
@@ -36,6 +36,10 @@ export interface NodeDriverOptions {
 	osConfig?: OSConfig;
 }
 
+export interface NodeExecutionFactoryOptions {
+	createIsolate?(memoryLimit: number): unknown;
+}
+
 /** Thin VFS adapter that delegates directly to `node:fs/promises`. */
 export class NodeFileSystem implements VirtualFileSystem {
 	async readFile(path: string): Promise<Uint8Array> {
@@ -392,11 +396,18 @@ export function createNodeDriver(options: NodeDriverOptions = {}): RuntimeDriver
 				...(options.osConfig ?? {}),
 			},
 		},
-		runtimeHooks: {
-			createIsolate: (memoryLimit) => createIsolate(memoryLimit),
-			createExecutionDriver: (runtimeOptions) =>
-				new NodeExecutionDriver(runtimeOptions),
-		},
+	};
+}
+
+export function createNodeExecutionFactory(
+	options: NodeExecutionFactoryOptions = {},
+): RuntimeExecutionDriverFactory {
+	return {
+		createExecutionDriver: (runtimeOptions) =>
+			new NodeExecutionDriver({
+				...runtimeOptions,
+				createIsolate: options.createIsolate,
+			}),
 	};
 }
 
diff --git a/packages/secure-exec/src/node/execution-driver.ts b/packages/secure-exec/src/node/execution-driver.ts
@@ -73,7 +73,9 @@ import type {
 	TimingMitigation,
 } from "../shared/api-types.js";
 
-export interface NodeExecutionDriverOptions extends RuntimeExecutionDriverOptions {}
+export interface NodeExecutionDriverOptions extends RuntimeExecutionDriverOptions {
+	createIsolate?(memoryLimit: number): unknown;
+}
 
 // Cache of bundled polyfills
 const polyfillCodeCache: Map<string, string> = new Map();
@@ -157,7 +159,7 @@ export class NodeExecutionDriver implements RuntimeExecutionDriver {
 		this.memoryLimit = options.memoryLimit ?? 128;
 		const driver = options.driver;
 		this.runtimeCreateIsolate =
-			(driver.runtimeHooks?.createIsolate as
+			(options.createIsolate as
 				| ((memoryLimit: number) => ivm.Isolate)
 				| undefined) ??
 			((memoryLimit) => createDefaultIsolate(memoryLimit));
diff --git a/packages/secure-exec/src/runtime-driver.ts b/packages/secure-exec/src/runtime-driver.ts
diff --git a/packages/secure-exec/src/types.ts b/packages/secure-exec/src/types.ts
diff --git a/packages/secure-exec/tests/index.test.ts b/packages/secure-exec/tests/index.test.ts
diff --git a/packages/secure-exec/tests/test-utils.ts b/packages/secure-exec/tests/test-utils.ts

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+schema: spec-driven`
	`2`	`+created: 2026-03-02`