chore: add driver-owned runtime proposal and refresh polyfills

Author: NathanFlurry

openspec/changes/driver-owned-node-runtime/.openspec.yaml

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

openspec/changes/driver-owned-node-runtime/design.md

@@ -0,0 +1,96 @@
+## Context
+
+`NodeProcess` currently combines two responsibilities: runtime orchestration and Node/`isolated-vm` execution internals. The constructor also accepts direct capability adapters and permissions, while `createNodeDriver` separately applies capability/permission defaults. This split causes ownership ambiguity and policy drift.
+
+This change adopts a strict boundary:
+- Driver owns capability and execution-heavy behavior.
+- `NodeProcess` remains the orchestrator for bridge/loader flow over a generic runtime-driver interface.
+- Runtime configuration (`processConfig`, `osConfig`) is always injected by `NodeProcess`, but sourced from the driver contract.
+
+For this phase, browser support is intentionally disabled to reduce cross-runtime coupling while the Node boundary is refactored.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Make `driver` required for `NodeProcess` construction.
+- Remove direct capability injection from `NodeProcess` options and move ownership into driver construction.
+- Normalize permission behavior to deny-by-default at driver level.
+- Keep bridge/loader orchestration in `NodeProcess` but drive it through a generic execution interface.
+- Preserve current Node runtime behavior (run/exec semantics, active-handle wait, host network facade) after boundary changes.
+- Temporarily disable browser runtime exports/paths during refactor.
+
+**Non-Goals:**
+- Restoring browser runtime support in this change.
+- Introducing new sandbox capabilities beyond the existing fs/network/child_process/process/os/runtime set.
+- Reworking bridge module semantics unrelated to ownership boundaries.
+
+## Decisions
+
+### 1. Require driver at construction
+
+**Choice:** `NodeProcessOptions.driver` becomes required, and constructor fallback logic that synthesizes a driver from raw options is removed.
+
+**Rationale:** This creates a single capability source of truth and removes implicit behavior.
+
+**Alternative considered:** Keep optional driver for backward compatibility. Rejected because it preserves split ownership and duplicate policy paths.
+
+### 2. Introduce a generic runtime-driver interface
+
+**Choice:** Define an internal runtime-driver contract that exposes execution lifecycle and capability handles consumed by `NodeProcess`.
+
+**Rationale:** `NodeProcess` can remain bridge/loader orchestrator while runtime-specific heavy lifting lives in Node driver implementation.
+
+**Alternative considered:** Move all runtime orchestration into driver and reduce `NodeProcess` to a shell. Rejected for this phase because bridge/loader sequencing remains shared orchestration logic.
+
+### 3. Move execution-heavy Node/isolated-vm behavior into Node driver
+
+**Choice:** Shift isolate lifecycle, module execution/caching, dynamic import handling, and host-side marshalling internals into Node driver-owned implementation.
+
+**Rationale:** These are runtime-specific concerns and should not live in a generic process facade.
+
+**Alternative considered:** Keep runtime internals in `NodeProcess` and only change constructor options. Rejected because it does not achieve driver ownership goals.
+
+### 4. Keep `processConfig`/`osConfig` injected by `NodeProcess`, sourced from driver
+
+**Choice:** `NodeProcess` continues to perform bridge/bootstrap injection, but config values are read from the required driver.
+
+**Rationale:** Preserves deterministic initialization point while aligning configuration ownership with driver contract.
+
+**Alternative considered:** Driver performs direct bridge/global injection. Rejected because it duplicates orchestration coupling and weakens shared initialization control.
+
+### 5. Deny-by-default capability policy in driver
+
+**Choice:** Driver defaults to reject all operations when permissions are not explicitly granted.
+
+**Rationale:** Security baseline should be explicit and centralized at the driver boundary.
+
+**Alternative considered:** Preserve permissive fallback when adapters are present. Rejected as unsafe and inconsistent with intended sandbox posture.
+
+### 6. Temporarily disable browser runtime paths
+
+**Choice:** Comment out browser-facing exports/integration paths for this phase and treat browser runtime as unsupported until re-enabled by a follow-up change.
+
+**Rationale:** Avoids maintaining parallel runtime semantics while core ownership boundaries are being refactored.
+
+**Alternative considered:** Keep browser runtime compiling with compatibility shims. Rejected to keep scope tight and reduce regression surface.
+
+## Risks / Trade-offs
+
+- **Breaking constructor and options contract** -> Mitigation: explicit migration in proposal/tasks and targeted updates across tests/examples/docs.
+- **Behavior drift during runtime logic move** -> Mitigation: preserve existing execution scenarios (CJS/ESM exports, dynamic import timing, active-handle waits, host network path) as acceptance criteria.
+- **Permission default regression** -> Mitigation: enforce driver-level deny-default tests and remove remaining permissive fallback paths.
+- **Temporary browser disable may affect consumers** -> Mitigation: clearly document unsupported status and require explicit follow-up change to restore.
+
+## Migration Plan
+
+1. Define new runtime-driver interfaces in `types.ts` and update `NodeProcessOptions` to require `driver`.
+2. Refactor Node driver implementation to own execution-heavy runtime responsibilities and capability policy defaults.
+3. Update `NodeProcess` to consume runtime-driver interface and keep bridge/loader orchestration + config injection flow.
+4. Disable/comment browser integration paths and document temporary unsupported state.
+5. Update tests and examples to required-driver construction; remove direct constructor adapter usage.
+6. Update compatibility/friction documentation and add follow-up for browser restoration.
+
+## Open Questions
+
+- Should browser disable behavior surface as compile-time absence of exports, runtime throw, or both?
+- Do we keep any public mutator methods on `NodeProcess` (currently none required), or make process instances fully immutable post-construction?

openspec/changes/driver-owned-node-runtime/proposal.md

@@ -0,0 +1,29 @@
+## Why
+
+`NodeProcess` currently mixes orchestration with Node/`isolated-vm` runtime implementation details, which makes driver boundaries unclear and keeps capability policy split across constructor fallbacks and driver construction. We need a strict driver-owned runtime model now to simplify ownership, enforce deny-by-default behavior consistently, and make future runtime backends easier to add.
+
+## What Changes
+
+- **BREAKING**: Require `NodeProcess` to be created with a `driver`; remove fallback construction of a default driver inside `NodeProcess`.
+- **BREAKING**: Remove direct capability injection options from `NodeProcess` (`filesystem`, `networkAdapter`, `commandExecutor`, `permissions`) and centralize capability setup in driver construction.
+- Move Node/`isolated-vm` execution-heavy responsibilities into `NodeDriver` implementation, while keeping `NodeProcess` as the bridge/loader orchestrator over a generic runtime-driver interface.
+- Make permission defaults explicit and secure: driver defaults to reject/deny all capability access unless permission checks are provided.
+- Keep `processConfig` and `osConfig` as required runtime inputs on `NodeProcess`, sourced from driver-owned configuration and injected by `NodeProcess` during bridge/bootstrap.
+- Temporarily disable browser runtime support for this phase by commenting out browser-facing paths and exports until driver-boundary refactor is stabilized.
+
+## Capabilities
+
+### New Capabilities
+- None.
+
+### Modified Capabilities
+- `runtime-execution-model`: tighten runtime construction contract (required driver), shift runtime ownership to driver-backed execution interface, and temporarily remove browser execution path requirements.
+
+## Impact
+
+- `packages/sandboxed-node/src/index.ts` (`NodeProcess` options/constructor contract, runtime orchestration boundary, browser exports and references)
+- `packages/sandboxed-node/src/node/driver.ts` (driver-owned runtime execution logic, deny-by-default permission defaults)
+- `packages/sandboxed-node/src/types.ts` (new generic runtime-driver interfaces and updated public constructor types)
+- `packages/sandboxed-node/src/browser/*` (commented-out or temporarily disabled integration surface)
+- `packages/sandboxed-node/tests/index.test.ts` and related call sites currently using `new NodeProcess()` or direct constructor adapters
+- README/examples/docs referencing constructor patterns and browser runtime availability

openspec/changes/driver-owned-node-runtime/specs/runtime-execution-model/spec.md

@@ -0,0 +1,43 @@
+## MODIFIED Requirements
+
+### Requirement: Unified Sandbox Execution Interface
+The project SHALL provide a stable Node sandbox execution interface, with `NodeProcess` exposing an `exec` path for running untrusted code and returning structured execution results, and a `run` path that returns module exports. Browser runtime execution support SHALL be disabled for this change phase.
+
+#### Scenario: Execute code in Node runtime
+- **WHEN** a caller creates `NodeProcess` with a valid 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: Browser runtime is disabled for this phase
+- **WHEN** a caller attempts to use browser sandbox runtime entrypoints during this change phase
+- **THEN** browser runtime execution MUST be unavailable under the runtime contract until a follow-up change restores support
+
+#### 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
+
+### 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. `NodeProcess` construction SHALL require a driver.
+
+#### Scenario: Node process uses configured adapters
+- **WHEN** `NodeProcess` 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: 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

openspec/changes/driver-owned-node-runtime/tasks.md

@@ -0,0 +1,30 @@
+## 1. Driver Contract and Public API
+
+- [ ] 1.1 Add a generic runtime-driver interface in `packages/sandboxed-node/src/types.ts` for execution lifecycle, capability handles, and runtime config access
+- [ ] 1.2 Update `NodeProcessOptions` in `packages/sandboxed-node/src/index.ts` to require `driver` and remove direct constructor capability options (`filesystem`, `networkAdapter`, `commandExecutor`, `permissions`)
+- [ ] 1.3 Remove optional constructor fallback driver creation in `NodeProcess` and simplify permission precedence to driver-owned policy only
+
+## 2. Move Node Runtime Heavy Lifting into Driver
+
+- [ ] 2.1 Refactor `packages/sandboxed-node/src/node/driver.ts` to own Node/`isolated-vm` execution-heavy logic (isolate lifecycle, module execution, dynamic import internals, host marshalling)
+- [ ] 2.2 Keep bridge/loader orchestration in `NodeProcess` over the new generic driver interface, with `processConfig` and `osConfig` injected by `NodeProcess` from driver-provided values
+- [ ] 2.3 Remove obsolete runtime-specific methods/fields from `NodeProcess` that become driver-owned
+
+## 3. Enforce Deny-by-Default Driver Policy
+
+- [ ] 3.1 Update Node driver defaults so missing permission checks reject all capability access
+- [ ] 3.2 Remove permissive fallback behavior in driver construction paths and align all driver-created adapters with explicit allow semantics
+- [ ] 3.3 Add/adjust tests for deny-by-default behavior under required-driver construction
+
+## 4. Temporarily Disable Browser Surface
+
+- [ ] 4.1 Comment out browser-facing exports and integration paths in `packages/sandboxed-node/src/index.ts` and package entrypoints for this phase
+- [ ] 4.2 Comment out browser runtime implementation paths under `packages/sandboxed-node/src/browser/` as needed to keep Node runtime refactor isolated
+- [ ] 4.3 Add clear temporary unsupported notes in code/docs to track browser restoration as follow-up work
+
+## 5. Migrate Tests, Docs, and Validation
+
+- [ ] 5.1 Update `packages/sandboxed-node/tests/index.test.ts` and related call sites to always construct `NodeProcess` with a driver
+- [ ] 5.2 Update README/examples/OpenSpec references that mention old constructor fallback or direct capability options
+- [ ] 5.3 Log migration friction and fix notes in `docs-internal/friction/sandboxed-node.md`, including temporary browser disable and restore follow-up
+- [ ] 5.4 Run targeted checks in `packages/sandboxed-node`: `pnpm run check-types`, targeted `vitest` coverage for NodeProcess/driver behavior, and any required spec-conformance checks