refactor: simplify runtime-driver test suites and archive openspec changes

Author: NathanFlurry

README.md

@@ -11,7 +11,7 @@ Run sandboxed Node.js code using a driver-based runtime.
 TODO:
 
 - **Node runtime**: isolated-vm backed sandbox execution with driver-owned capability wiring.
-- **Browser runtime**: temporarily disabled during the driver-owned runtime refactor.
+- **Browser runtime**: Worker-backed execution through `NodeRuntime` + browser driver factories.
 - **Driver-based**: Provide a driver to map filesystem, network, and child_process.
 - **Permissions**: Gate syscalls with custom allow/deny functions.
 - **Opt-in system features**: Disable network/child_process/FS by omission.

docs-internal/arch/overview.md

@@ -1,18 +1,19 @@
 # Architecture Overview
 
 ```
-NodeRuntime  →  SystemDriver + RuntimeDriverFactory  →  NodeExecutionDriver
-  (API)          (capability/config + execution wiring)           (isolated-vm engine)
+NodeRuntime
+  → SystemDriver + RuntimeDriverFactory
+  → NodeExecutionDriver (node target) | BrowserRuntimeDriver + Worker runtime (browser target)
 ```
 
 ## NodeRuntime
 
 `src/index.ts`
 
-Public API. Thin facade — delegates everything to the execution driver.
+Public API. Thin facade that delegates orchestration to a runtime driver.
 
 - `run(code)` — execute as module, get exports back
-- `exec(code)` — execute as script, get exit code + stdout/stderr
+- `exec(code)` — execute as script, get exit code/error contract
 - `dispose()` / `terminate()`
 - Requires both:
   - `systemDriver` for runtime capabilities/config
@@ -53,6 +54,26 @@ Factory that builds a Node-backed `RuntimeDriverFactory`.
 - Constructs `NodeExecutionDriver` instances
 - Owns optional Node-specific isolate creation hook
 
+### createBrowserDriver()
+
+`src/browser/driver.ts`
+
+Factory that builds a browser `SystemDriver` with browser-native adapters.
+
+- Uses OPFS or in-memory filesystem adapters
+- Uses fetch-backed network adapter with deterministic `ENOSYS` for unsupported DNS/server paths
+- Applies permission wrappers before returning the driver
+
+### createBrowserRuntimeDriverFactory()
+
+`src/browser/runtime-driver.ts`
+
+Factory that builds a browser-backed `RuntimeDriverFactory`.
+
+- Validates and rejects Node-only runtime options
+- Constructs `BrowserRuntimeDriver` instances
+- Owns worker URL/runtime-driver creation options
+
 ## NodeExecutionDriver
 
 `src/node/execution-driver.ts`
@@ -64,6 +85,28 @@ The engine. Owns the `isolated-vm` isolate and bridges host capabilities in.
 - Caches compiled modules and resolved formats per isolate
 - Enforces payload size limits on bridge transfers
 
+## BrowserRuntimeDriver
+
+`src/browser/runtime-driver.ts`
+
+Browser execution driver that owns worker lifecycle and message marshalling.
+
+- Spawns and manages the browser runtime worker
+- Dispatches `run`/`exec` requests and correlates responses by request ID
+- Streams optional stdio events to host hooks without runtime-managed output buffering
+- Exposes the configured browser network adapter through `NodeRuntime.network`
+
+## Browser Worker Runtime
+
+`src/browser/worker.ts`
+
+Worker-side runtime implementation used by the browser runtime driver.
+
+- Initializes browser bridge globals and runtime config from worker init payload
+- Executes transformed CJS/ESM user code and returns runtime-contract results
+- Uses permission-aware filesystem/network adapters in the worker context
+- Preserves deterministic unsupported-operation contracts (for example DNS gaps)
+
 ## ModuleAccessFileSystem
 
 `src/node/module-access.ts`

docs-internal/friction.md

@@ -1,5 +1,11 @@
 # Sandboxed Node Friction Log
 
+## 2026-03-02
+
+1. **[resolved]** Browser runtime execution was intentionally disabled during runtime-driver boundary refactor.
+   - Symptom: browser entrypoints threw deterministic unsupported errors, so runtime-driver integration coverage could only exercise Node execution paths.
+   - Fix: restored browser runtime through `NodeRuntime` driver composition (`createBrowserDriver` + `createBrowserRuntimeDriverFactory`), moved worker lifecycle/marshalling into browser runtime-driver implementation, and added shared node/browser runtime-contract integration suites plus browser runner wiring.
+
 ## 2026-03-01
 
 1. **[resolved]** `NodeRuntime` constructor ownership drifted between driver and direct adapter options.

docs-internal/research/comparison/isolation-mechanisms.md

@@ -177,7 +177,7 @@ A comparison of sandboxing and isolation approaches relevant to running untruste
 - `eval()` in Workers is not isolated from the Worker's own globals
 - No memory limits — a Worker can consume arbitrary memory
 
-**libsandbox relevance:** This is libsandbox's browser isolation mechanism. The BrowserSandbox class creates a Web Worker and communicates via a request/response protocol over `postMessage`. Note that Worker isolation is weaker than isolated-vm — code in the Worker has full access to the Worker global scope.
+**libsandbox relevance:** This is libsandbox's browser isolation mechanism. `NodeRuntime` uses a browser runtime driver that creates a Web Worker and communicates via a request/response protocol over `postMessage`. Note that Worker isolation is weaker than isolated-vm — code in the Worker has full access to the Worker global scope.
 
 ---
 

docs/quickstart.mdx

@@ -30,4 +30,26 @@ description: Get secure-exec running from TypeScript in a few minutes.
     await proc.dispose();
     ```
   </Step>
+  <Step title="Execute code in browser">
+    ```ts
+    import {
+      NodeRuntime,
+      createBrowserDriver,
+      createBrowserRuntimeDriverFactory,
+    } from "secure-exec/browser";
+
+    const runtime = new NodeRuntime({
+      systemDriver: await createBrowserDriver({
+        filesystem: "memory",
+      }),
+      runtimeDriverFactory: createBrowserRuntimeDriverFactory(),
+    });
+
+    const result = await runtime.exec("console.log('hello from browser runtime')");
+    if (result.errorMessage) {
+      throw new Error(result.errorMessage);
+    }
+    await runtime.terminate();
+    ```
+  </Step>
 </Steps>

openspec/changes/archive/2026-03-02-restore-browser-runtime-driver/.openspec.yaml

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

openspec/changes/archive/2026-03-02-restore-browser-runtime-driver/design.md

@@ -0,0 +1,78 @@
+## Context
+
+The runtime architecture has converged on a universal `NodeRuntime` orchestrator that composes a capability-side `SystemDriver` with an execution-side `RuntimeDriverFactory`. During the boundary refactor, browser execution was intentionally disabled and `BrowserSandbox` was left as a throwing compatibility surface.
+
+The next step is to restore browser execution without reintroducing split APIs or duplicated orchestration logic. The design target is one runtime API (`NodeRuntime`) with driver-only variation, plus reusable integration tests that assert runtime-contract behavior across `node` and `browser` execution targets.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Restore browser execution using the existing `NodeRuntime` + runtime-driver architecture.
+- Remove `BrowserSandbox` and keep one universal runtime API.
+- Keep capability ownership in `SystemDriver` and move browser execution heavy lifting into a browser runtime driver implementation.
+- Enforce deterministic validation for Node-only options when browser runtime is selected.
+- Introduce reusable integration suites (`run*` functions) that can be executed with a shared `TestContext` class for both node and browser targets.
+
+**Non-Goals:**
+- Backward compatibility for `BrowserSandbox` or legacy constructor aliases.
+- Adding new capability domains beyond existing fs/network/child-process/env/runtime behavior.
+- Full cross-browser matrix expansion in this change (single supported browser engine is sufficient initially).
+
+## Decisions
+
+### 1. Keep `NodeRuntime` as the only execution API
+
+- **Choice:** Browser execution is restored by adding a browser `RuntimeDriverFactory`, not by reintroducing a separate browser runtime class.
+- **Rationale:** This preserves the architecture goal that only the driver changes across targets.
+- **Alternative considered:** Keep `BrowserSandbox` as a wrapper around `NodeRuntime`; rejected because it keeps parallel public runtime surfaces and API drift risk.
+
+### 2. Move browser runtime heavy lifting into browser runtime driver
+
+- **Choice:** Implement browser execution lifecycle in browser runtime-driver code (worker spin-up/teardown, message protocol, runtime marshalling, and browser bridge shims).
+- **Rationale:** Mirrors Node driver ownership and keeps `NodeRuntime` focused on orchestration.
+- **Alternative considered:** Put browser worker orchestration directly in `NodeRuntime`; rejected because it breaks driver boundary consistency.
+
+### 3. Keep `createBrowserDriver` as capability-side `SystemDriver` factory
+
+- **Choice:** `createBrowserDriver` returns a `SystemDriver` (OPFS/in-memory filesystem, browser fetch-backed network adapter, permission wrappers) and pairs with a separate browser runtime-driver factory.
+- **Rationale:** Capability composition remains symmetric across node and browser targets.
+- **Alternative considered:** Make browser runtime-driver implicitly create capability adapters; rejected because it conflates capability and execution layers.
+
+### 4. Reject Node-only execution options for browser target
+
+- **Choice:** Browser runtime-driver factory performs explicit validation and rejects `memoryLimit`, `cpuTimeLimitMs`, `timingMitigation`, and payload-limit overrides.
+- **Rationale:** These options are Node/isolated-vm-specific and silently ignoring them would create unsafe ambiguity.
+- **Alternative considered:** Ignore unsupported fields for browser; rejected because misconfiguration would pass silently.
+
+### 5. Shared integration harness with class-based context
+
+- **Choice:** Add `tests/integration/` suites exporting `runX(ctx: TestContext)` functions, and one orchestrator test that loops targets (`node`, `browser`) and executes all shared suites under `describe` blocks.
+- **Rationale:** Reuses existing runtime-contract tests while preventing node/browser drift.
+- **Alternative considered:** Duplicate separate node and browser spec files; rejected due to maintenance overhead and parity gaps.
+
+### 6. Run browser integration through a browser test runner profile
+
+- **Choice:** Add a dedicated browser integration runner configuration and script that executes the same suite in a real browser engine.
+- **Rationale:** Browser runtime behavior (Worker/OPFS/fetch semantics) needs real-browser validation.
+- **Alternative considered:** Node-only emulation for browser tests; rejected because it cannot validate critical browser runtime primitives.
+
+## Risks / Trade-offs
+
+- [Browser runtime contract mismatch with Node semantics] -> Mitigation: keep shared `run*` integration suites as parity gates and document intentional deviations in friction docs.
+- [Browser tests are slower/flakier than node tests] -> Mitigation: keep browser suite targeted and under one minute, run full matrix only in dedicated CI lanes.
+- [Removal of `BrowserSandbox` breaks existing consumers] -> Mitigation: treat as explicit breaking change with updated docs/examples in the same change.
+- [Capability gaps in browser adapters (for example DNS/HTTP2)] -> Mitigation: keep deterministic `ENOSYS` contracts and spec coverage for unsupported operations.
+
+## Migration Plan
+
+1. Implement browser runtime driver factory and runtime-driver class that satisfy `RuntimeDriver` contract.
+2. Re-enable `createBrowserDriver` capability factory and remove/retire `BrowserSandbox` exports.
+3. Add browser target wiring in test utilities via a class-based `TestContext` abstraction.
+4. Migrate selected existing runtime-contract tests into reusable `tests/integration/run*.ts` suites.
+5. Add node and browser integration entrypoints that execute the same `run*` suites by target.
+6. Update docs/specs/friction notes and run targeted typecheck/test commands for node and browser profiles.
+
+## Open Questions
+
+- Which single browser engine should be the default CI gate in phase one (Chromium recommended)?
+- Should unsupported browser options fail at `NodeRuntime` construction time or runtime-driver factory creation time (factory-time preferred for clearer ownership)?

openspec/changes/archive/2026-03-02-restore-browser-runtime-driver/proposal.md

@@ -0,0 +1,38 @@
+## Why
+
+Browser runtime execution is currently disabled while the runtime-driver architecture has already converged on a universal `NodeRuntime` API. We need to restore browser support now by implementing a browser runtime driver and validating behavior parity with reusable integration tests.
+
+## What Changes
+
+- **BREAKING**: Remove `BrowserSandbox` as a public execution API and standardize on `NodeRuntime` with runtime-driver selection (`node` vs `browser`).
+- Add a browser `RuntimeDriverFactory` implementation that performs the browser-specific execution heavy lifting (worker lifecycle, host bridge wiring, and browser capability shims) while reusing the same `NodeRuntime` orchestration contract.
+- Restore browser capability driver construction (`createBrowserDriver`) and wire it to the same `SystemDriver` + `RuntimeDriverFactory` composition model as Node.
+- Enforce deterministic option validation for browser runtime-driver creation: reject Node-only runtime options (`memoryLimit`, `cpuTimeLimitMs`, `timingMitigation`, and payload-limit overrides) when targeting browser execution.
+- Add a shared integration harness built around a `TestContext` class and reusable `run*` suites that execute the same runtime-contract tests for both driver targets.
+- Keep existing deny-by-default permissions behavior and runtime capability contracts consistent across both targets.
+
+## Capabilities
+
+### New Capabilities
+- `runtime-driver-integration-testing`: Shared integration test harness that runs reusable runtime suites against multiple runtime-driver targets with one contract surface.
+
+### Modified Capabilities
+- `node-runtime`: Runtime execution support is expanded from Node-only phase behavior to include browser runtime-driver execution via `NodeRuntime`; browser-disabled requirements are removed and replaced with parity/validation requirements.
+- `compatibility-governance`: Validation policy requires targeted integration coverage that runs shared runtime-contract suites across both node and browser runtime-driver targets.
+
+## Impact
+
+- Affected runtime API and implementation:
+  - `packages/secure-exec/src/index.ts`
+  - `packages/secure-exec/src/runtime-driver.ts`
+  - `packages/secure-exec/src/browser/driver.ts`
+  - `packages/secure-exec/src/browser/worker.ts`
+  - `packages/secure-exec/src/browser/index.ts` (removal or deprecation path)
+  - `packages/secure-exec/src/node/driver.ts`
+- Affected tests:
+  - New integration suite directory under `packages/secure-exec/tests/integration/`
+  - Existing `packages/secure-exec/tests/test-utils.ts` and selected runtime tests migrated to shared `run*` suites
+- Affected docs/specs:
+  - `openspec/specs/node-runtime/spec.md`
+  - `openspec/specs/compatibility-governance/spec.md`
+  - compatibility/friction docs and runtime API docs referencing browser runtime availability

openspec/changes/archive/2026-03-02-restore-browser-runtime-driver/specs/compatibility-governance/spec.md

@@ -0,0 +1,19 @@
+## ADDED Requirements
+
+### Requirement: Runtime Driver Contract Changes MUST Run Shared Cross-Target Integration Suites
+Any change that modifies runtime-driver behavior or runtime orchestration contracts MUST run shared integration suites against both node and browser runtime-driver targets.
+
+#### Scenario: Runtime/driver implementation changes trigger cross-target validation
+- **WHEN** a change modifies runtime contracts or driver behavior under `packages/secure-exec/src/index.ts`, `src/runtime-driver.ts`, `src/node/**`, or `src/browser/**`
+- **THEN** the change MUST execute shared integration suites for both node and browser targets before completion
+
+#### Scenario: Shared suites are reused between targets
+- **WHEN** runtime integration coverage is executed for node and browser
+- **THEN** both targets MUST run the same reusable `run*` contract suites rather than target-specific duplicated logic
+
+### Requirement: Browser Runtime Validation Workflow MUST Remain Available To Contributors
+Repository scripts and test wiring MUST provide a documented way to run browser runtime integration tests locally using the shared runtime-contract suites.
+
+#### Scenario: Contributor runs targeted browser integration validation
+- **WHEN** a contributor runs the documented browser integration command
+- **THEN** the runtime integration suite MUST execute in a real browser environment and report pass/fail for the shared contract suites

openspec/changes/archive/2026-03-02-restore-browser-runtime-driver/specs/node-runtime/spec.md

@@ -0,0 +1,48 @@
+## MODIFIED Requirements
+
+### Requirement: Unified Sandbox Execution Interface
+The project SHALL provide a stable sandbox execution interface through `NodeRuntime`, with `exec` for running untrusted code and returning structured execution results and `run` for module-export evaluation. Runtime-driver target selection (node or browser) MUST not require separate runtime classes.
+
+#### Scenario: Execute code in Node runtime target
+- **WHEN** a caller creates `NodeRuntime` with a Node-target runtime driver and invokes `exec`
+- **THEN** the sandbox MUST run the provided code in an isolated execution context and return structured output for the caller
+
+#### Scenario: Execute code in browser runtime target
+- **WHEN** a caller creates `NodeRuntime` with a browser-target runtime driver and invokes `exec`
+- **THEN** execution MUST run through browser runtime primitives and return the same structured runtime result contract
+
+#### Scenario: Run CJS module and retrieve exports
+- **WHEN** a caller invokes `run()` with CommonJS code that assigns to `module.exports`
+- **THEN** the result's `exports` field MUST contain the value of `module.exports`
+
+#### Scenario: Run ESM module and retrieve namespace exports
+- **WHEN** a caller invokes `run()` with ESM code that uses `export` declarations
+- **THEN** the result's `exports` field MUST contain the module namespace object with all named exports and the `default` export (if declared)
+
+#### Scenario: Run ESM module with only a default export
+- **WHEN** a caller invokes `run()` with ESM code containing `export default <value>`
+- **THEN** the result's `exports` field MUST be an object with a `default` property holding that value
+
+#### Scenario: Run ESM module with named and default exports
+- **WHEN** a caller invokes `run()` with ESM code containing both `export default` and named `export` declarations
+- **THEN** the result's `exports` field MUST be an object containing both the `default` property and all named export properties
+
+## ADDED Requirements
+
+### Requirement: Browser Runtime Driver Rejects Node-Only Execution Options
+Browser-target runtime-driver construction MUST reject Node-specific runtime options that are unsupported in browser execution.
+
+#### Scenario: Browser runtime rejects Node-only execution controls
+- **WHEN** a caller creates `NodeRuntime` with a browser runtime-driver factory and passes any of `memoryLimit`, `cpuTimeLimitMs`, `timingMitigation`, or payload-limit overrides
+- **THEN** construction MUST fail with a deterministic validation error indicating unsupported browser runtime options
+
+#### Scenario: Browser runtime accepts baseline cross-target options
+- **WHEN** a caller creates `NodeRuntime` with a browser runtime-driver factory using only cross-target options (for example `systemDriver`, `runtimeDriverFactory`, and optional `onStdio`)
+- **THEN** runtime construction MUST succeed and preserve runtime execution behavior
+
+### Requirement: BrowserSandbox API Surface Is Removed
+The runtime contract MUST expose browser execution through `NodeRuntime` driver composition and MUST NOT require a separate `BrowserSandbox` execution class.
+
+#### Scenario: Runtime entrypoint is unified by driver target
+- **WHEN** a caller needs browser execution behavior
+- **THEN** they MUST construct `NodeRuntime` with browser system/runtime drivers rather than a separate browser sandbox runtime class