refactor: rename system and runtime driver contracts

Author: NathanFlurry

docs-internal/arch/overview.md

@@ -1,7 +1,7 @@
 # Architecture Overview
 
 ```
-NodeRuntime  →  RuntimeDriver + RuntimeExecutionDriverFactory  →  NodeExecutionDriver
+NodeRuntime  →  SystemDriver + RuntimeDriverFactory  →  NodeExecutionDriver
   (API)          (capability/config + execution wiring)           (isolated-vm engine)
 ```
 
@@ -15,10 +15,10 @@ Public API. Thin facade — delegates everything to the execution driver.
 - `exec(code)` — execute as script, get exit code + stdout/stderr
 - `dispose()` / `terminate()`
 - Requires both:
-  - `driver` for runtime capabilities/config
-  - `executionFactory` for execution-driver construction
+  - `systemDriver` for runtime capabilities/config
+  - `runtimeDriverFactory` for runtime-driver construction
 
-## RuntimeDriver
+## SystemDriver
 
 `src/runtime-driver.ts` (re-exported from `src/types.ts`)
 
@@ -29,26 +29,26 @@ Config object that bundles what the sandbox can access. Deny-by-default.
 - `commandExecutor` — child processes
 - `permissions` — per-adapter allow/deny checks
 
-## RuntimeExecutionDriverFactory
+## RuntimeDriverFactory
 
-Factory abstraction for constructing execution drivers from normalized runtime options.
+Factory abstraction for constructing runtime drivers from normalized runtime options.
 
-- `createExecutionDriver(options)` — returns a `RuntimeExecutionDriver`
+- `createRuntimeDriver(options)` — returns a `RuntimeDriver`
 
 ### createNodeDriver()
 
 `src/node/driver.ts`
 
-Factory that builds a `RuntimeDriver` with Node-native adapters.
+Factory that builds a `SystemDriver` with Node-native adapters.
 
 - Wraps filesystem in `ModuleAccessFileSystem` (read-only `node_modules` overlay)
 - Optionally wires up network and command executor
 
-### createNodeExecutionFactory()
+### createNodeRuntimeDriverFactory()
 
 `src/node/driver.ts`
 
-Factory that builds a Node-backed `RuntimeExecutionDriverFactory`.
+Factory that builds a Node-backed `RuntimeDriverFactory`.
 
 - Constructs `NodeExecutionDriver` instances
 - Owns optional Node-specific isolate creation hook

docs/quickstart.mdx

@@ -11,11 +11,11 @@ description: Get secure-exec running from TypeScript in a few minutes.
   </Step>
   <Step title="Execute code">
     ```ts
-    import { NodeRuntime, createNodeDriver, createNodeExecutionFactory } from "secure-exec";
+    import { NodeRuntime, createNodeDriver, createNodeRuntimeDriverFactory } from "secure-exec";
 
     const proc = new NodeRuntime({
-      driver: createNodeDriver({}),
-      executionFactory: createNodeExecutionFactory(),
+      systemDriver: createNodeDriver({}),
+      runtimeDriverFactory: createNodeRuntimeDriverFactory(),
     });
     const logs: string[] = [];
     const result = await proc.exec("console.log('hello from secure-exec')", {

examples/hono/loader/src/index.ts

@@ -8,7 +8,7 @@ import {
   NodeFileSystem,
   NodeRuntime,
   createNodeDriver,
-  createNodeExecutionFactory,
+  createNodeRuntimeDriverFactory,
 } from "../../../../packages/secure-exec/src/index.ts";
 import {
   LOOPBACK_HOST,
@@ -33,8 +33,8 @@ function createProcess(runnerRoot: string, runnerEntry: string): NodeRuntime {
   });
 
   return new NodeRuntime({
-    driver,
-    executionFactory: createNodeExecutionFactory(),
+    systemDriver: driver,
+    runtimeDriverFactory: createNodeRuntimeDriverFactory(),
   });
 }
 

examples/just-bash/src/index.ts

@@ -3,7 +3,7 @@ import {
   allowAll,
   NodeRuntime,
   createNodeDriver,
-  createNodeExecutionFactory,
+  createNodeRuntimeDriverFactory,
   type CommandExecutor,
   type SpawnedProcess,
   type VirtualFileSystem,
@@ -94,8 +94,8 @@ async function main(): Promise<void> {
   });
 
   const proc = new NodeRuntime({
-    driver,
-    executionFactory: createNodeExecutionFactory(),
+    systemDriver: driver,
+    runtimeDriverFactory: createNodeRuntimeDriverFactory(),
   });
   const result = await proc.exec(`
     const { execSync } = require('child_process');

openspec/changes/archive/2026-03-02-rename-systemdriver-runtimedriver-pair/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-02

openspec/changes/archive/2026-03-02-rename-systemdriver-runtimedriver-pair/design.md

@@ -0,0 +1,33 @@
+## Context
+
+The runtime already separates capability/config ownership from execution construction, but terminology still causes confusion because capability-side and execution-side contracts both read as runtime concerns. This change aligns names to intent.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Name capability-side contract `SystemDriver`.
+- Name execution-side contract `RuntimeDriver` and its factory/options accordingly.
+- Keep runtime behavior and security semantics unchanged.
+- Apply names consistently across code, tests, docs, and examples.
+
+**Non-Goals:**
+- Changing execution semantics or permission behavior.
+- Reworking module loading internals.
+
+## Decisions
+
+1. Rename top-level contracts instead of alias-only layering.
+- Rationale: clear API surface and avoids perpetuating old ambiguity.
+
+2. Rename constructor fields to match pair semantics.
+- `NodeRuntimeOptions.driver` -> `systemDriver`
+- `NodeRuntimeOptions.executionFactory` -> `runtimeDriverFactory`
+- Rationale: makes call sites self-descriptive.
+
+3. Keep Node-specific execution class name as-is for now.
+- Rationale: scope control; core pair naming is the priority.
+
+## Risks / Trade-offs
+
+- [Breaking API] External call sites must update names. → Mitigation: update docs/examples/tests in the same change.
+- [Partial rename drift] Missed symbols can cause confusion. → Mitigation: repository-wide symbol replacement and typecheck/test validation.

openspec/changes/archive/2026-03-02-rename-systemdriver-runtimedriver-pair/proposal.md

@@ -0,0 +1,25 @@
+## Why
+
+The current driver naming still conflates capability-side and execution-side ownership, making APIs harder to read and discuss. We want the names to map directly to responsibilities: `SystemDriver` for OS/capability simulation and `RuntimeDriver` for runtime execution management.
+
+## What Changes
+
+- Rename capability-side driver type from `RuntimeDriver` to `SystemDriver`.
+- Rename execution-side contracts from `RuntimeExecutionDriver*` to `RuntimeDriver*`.
+- Update Node runtime constructor and factory naming to reflect the new pair (`systemDriver` + `runtimeDriverFactory`).
+- Keep behavior unchanged: deny-by-default, runtime config injection, and execution semantics remain the same.
+- Update docs/examples/tests to use the new names.
+
+## Capabilities
+
+### New Capabilities
+- None.
+
+### Modified Capabilities
+- `node-runtime`: API contract terminology for driver composition is renamed to `SystemDriver` (capability side) and `RuntimeDriver` (execution side) without runtime behavior changes.
+
+## Impact
+
+- Affected code: runtime driver typings, NodeRuntime constructor options, Node factory exports, tests/docs/examples.
+- API impact: **BREAKING** public type/function names and constructor option field names are renamed.
+- No new dependencies.

openspec/changes/archive/2026-03-02-rename-systemdriver-runtimedriver-pair/specs/node-runtime/spec.md

@@ -0,0 +1,20 @@
+## MODIFIED Requirements
+
+### Requirement: Driver-Based Capability Composition
+Runtime capabilities SHALL be composed through host-provided system 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-side `SystemDriver` and an execution-side `RuntimeDriverFactory`.
+
+#### Scenario: Node runtime uses configured adapters with explicit runtime driver factory
+- **WHEN** `NodeRuntime` is created with a `SystemDriver` that defines filesystem, network, and command-execution adapters and with a `RuntimeDriverFactory`
+- **THEN** sandboxed operations MUST route through those adapters for capability access and execution MUST be created through the provided runtime driver factory
+
+#### Scenario: Missing permissions deny capability access by default
+- **WHEN** a system 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 system-driver configuration
+- **THEN** corresponding sandbox operations MUST be unavailable or denied by the runtime contract
+
+#### Scenario: Runtime process/os config remains system-driver-owned
+- **WHEN** a caller provides runtime `process` and `os` configuration on the system driver
+- **THEN** `NodeRuntime` MUST source and inject that configuration into runtime-driver creation

openspec/changes/archive/2026-03-02-rename-systemdriver-runtimedriver-pair/tasks.md

@@ -0,0 +1,17 @@
+## 1. Core Type Renames
+
+- [x] 1.1 Rename capability-side `RuntimeDriver` contracts/types to `SystemDriver`.
+- [x] 1.2 Rename execution-side `RuntimeExecutionDriver*` contracts/types to `RuntimeDriver*`.
+- [x] 1.3 Update exports/re-exports to expose the new names.
+
+## 2. Runtime and Node Wiring
+
+- [x] 2.1 Update `NodeRuntimeOptions` and constructor fields to `systemDriver` + `runtimeDriverFactory`.
+- [x] 2.2 Update Node driver factory naming/typing to match new pair semantics.
+- [x] 2.3 Update browser typings/imports impacted by renamed contracts.
+
+## 3. Documentation and Validation
+
+- [x] 3.1 Update docs/examples/tests to new names.
+- [x] 3.2 Run targeted typecheck/tests.
+- [x] 3.3 Mark tasks complete and confirm OpenSpec status.

openspec/specs/node-runtime/spec.md

@@ -31,23 +31,23 @@ 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 both a capability driver and an execution factory.
+Runtime capabilities SHALL be composed through host-provided system 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-side `SystemDriver` and an execution-side `RuntimeDriverFactory`.
 
-#### 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: Node runtime uses configured adapters with explicit runtime driver factory
+- **WHEN** `NodeRuntime` is created with a `SystemDriver` that defines filesystem, network, and command-execution adapters and with a `RuntimeDriverFactory`
+- **THEN** sandboxed operations MUST route through those adapters for capability access and execution MUST be created through the provided runtime driver factory
 
 #### Scenario: Missing permissions deny capability access by default
-- **WHEN** a driver is configured without explicit permission allowance for a capability domain
+- **WHEN** a system 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
+- **WHEN** a capability adapter is omitted from system-driver 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
+#### Scenario: Runtime process/os config remains system-driver-owned
+- **WHEN** a caller provides runtime `process` and `os` configuration on the system driver
+- **THEN** `NodeRuntime` MUST source and inject that configuration into runtime-driver 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.