chore: console log -> stdio

Author: NathanFlurry

CLAUDE.md

@@ -15,7 +15,7 @@
 
 ## Node Architecture
 
-- read `docs-internal/arch/overview.md` for the component map (NodeProcess, SandboxDriver, NodeDriver, NodeExecutionDriver, ModuleAccessFileSystem, Permissions)
+- read `docs-internal/arch/overview.md` for the component map (NodeRuntime, RuntimeDriver, NodeDriver, NodeExecutionDriver, ModuleAccessFileSystem, Permissions)
 - keep it up to date when adding, removing, or significantly changing components
 
 ## Specs Source of Truth
@@ -26,6 +26,7 @@
 - use `openspec/specs/README.md` for how to reference baseline capabilities in new change proposals
 - track development friction in `docs-internal/friction.md` (mark resolved items with fix notes)
 - OpenSpec proposals/design/tasks MUST explicitly list the concrete tests to add or update for the change
+- when a request is scoped as `opsx` (propose/plan/apply/archive), always use OpenSpec workflow end-to-end (`opsx propose` -> `opsx apply`) before implementation; do not apply code changes outside an active OpenSpec change
 
 ## Compatibility Project-Matrix Policy
 

docs-internal/friction.md

@@ -12,7 +12,7 @@
 
 3. **[resolved]** Default console capture buffered unbounded host memory.
    - Symptom: runtime execution accumulated console output in host-managed `stdout`/`stderr` arrays by default, enabling memory amplification under high-volume logs.
-   - Fix: runtime now drops console output by default and exposes an explicit streaming hook (`onConsoleLog`) for host-controlled log handling.
+   - Fix: runtime now drops console output by default and exposes an explicit streaming hook (`onStdio`) for host-controlled log handling.
    - Compatibility trade-off: `exec()`/`run()` no longer mirror Node stdout/stderr buffering by default; result payloads no longer expose `stdout`/`stderr` fields, so consumers that need logs must opt into hook-based streaming.
    - Migration note: switch any `result.stderr` checks to `result.errorMessage` for runtime error assertions.
 4. **[resolved]** Node module loading depended on allowlist projection setup and split filesystem paths.

docs/node-compatability.mdx

@@ -58,7 +58,7 @@ Unsupported modules use: `"<module> is not supported in sandbox"`.
 - `console.log`/`warn`/`error` are supported and serialize arguments with circular-safe bounded formatting.
 - `exec()`/`run()` results do not expose buffered `stdout`/`stderr` fields.
 - By default, secure-exec drops console emissions instead of buffering runtime-managed output.
-- Consumers that need logs should use the explicit `onConsoleLog` hook to stream `stdout`/`stderr` events in emission order.
+- Consumers that need logs should use the explicit `onStdio` hook to stream `stdout`/`stderr` events in emission order.
 
 ## Node-Modules Overlay Behavior
 

docs/quickstart.mdx

@@ -11,12 +11,12 @@ description: Get secure-exec running from TypeScript in a few minutes.
   </Step>
   <Step title="Execute code">
     ```ts
-    import { NodeProcess, createNodeDriver } from "secure-exec";
+    import { NodeRuntime, createNodeDriver } from "secure-exec";
 
-    const proc = new NodeProcess({ driver: createNodeDriver({}) });
+    const proc = new NodeRuntime({ driver: createNodeDriver({}) });
     const logs: string[] = [];
     const result = await proc.exec("console.log('hello from secure-exec')", {
-      onConsoleLog: (event) => {
+      onStdio: (event) => {
         logs.push(`[${event.channel}] ${event.message}`);
       },
     });

docs/security-model.mdx

@@ -81,5 +81,5 @@ The bridge also enforces isolate-boundary payload limits so oversized base64 fil
 ## Logging Contract
 
 - Console output is **not buffered** into runtime-managed execution result fields by default (`exec()`/`run()` do not expose `stdout`/`stderr` result fields).
-- To consume logs, configure the optional `onConsoleLog` streaming hook and forward events to your own sink.
+- To consume logs, configure the optional `onStdio` streaming hook and forward events to your own sink.
 - This avoids implicit host-memory growth from untrusted high-volume logging.

openspec/changes/archive/2026-03-01-rename-runtime-driver-and-node-runtime/.openspec.yaml

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

openspec/changes/archive/2026-03-01-rename-runtime-driver-and-node-runtime/design.md

@@ -0,0 +1,47 @@
+## Context
+
+The runtime refactor already split responsibilities to a thin runtime facade and driver-owned execution internals. However, the public names still used legacy `NodeProcess` and `SandboxDriver` terminology, which obscured the intended ownership model and conflicted with the architecture docs.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Rename the runtime facade type from `NodeProcess` to `NodeRuntime`.
+- Rename the driver contract from `SandboxDriver` to `RuntimeDriver`.
+- Keep runtime behavior unchanged while updating symbols, imports, and docs.
+- Rename the dedicated driver type file to `runtime-driver.ts` and keep `types.ts` as the compatibility export surface.
+
+**Non-Goals:**
+- Rework runtime execution semantics, permissions policy, or module-access behavior.
+- Restore browser runtime support.
+- Change low-level isolate/bridge orchestration.
+
+## Decisions
+
+1. Rename symbols directly instead of introducing aliases.
+- Rationale: avoid long-term dual API maintenance and ambiguity.
+- Alternative: export deprecated aliases (`NodeProcess`, `SandboxDriver`). Rejected for now to keep API surface explicit.
+
+2. Keep `types.ts` as the import gateway for shared contracts.
+- Rationale: existing imports already point to `types.ts`; moving declarations to `runtime-driver.ts` with re-exports gives cleaner ownership with lower migration risk.
+- Alternative: force every consumer to import from `runtime-driver.ts`. Rejected as unnecessary churn.
+
+3. Update OpenSpec baseline specs to new names.
+- Rationale: capability requirements must reflect the current external contract.
+- Alternative: keep old names in specs with translation notes. Rejected to prevent drift.
+
+## Risks / Trade-offs
+
+- [Breaking symbol rename] -> Mitigation: update all local call sites (src/tests/examples/docs/specs) in one pass and verify with typecheck/tests.
+- [Residual old references in docs/specs] -> Mitigation: run repository-wide symbol scans after rename and patch remaining hits.
+- [Behavior regression masked as rename] -> Mitigation: run targeted Node runtime and module-access suites after rename.
+
+## Migration Plan
+
+1. Rename `driver-types.ts` to `runtime-driver.ts` and rename `SandboxDriver` to `RuntimeDriver`.
+2. Rename `NodeProcess`/`NodeProcessOptions` to `NodeRuntime`/`NodeRuntimeOptions` in source and exports.
+3. Update tests/examples/docs/spec references.
+4. Validate with `tsc` and targeted vitest suites.
+
+## Open Questions
+
+- Do we want temporary compatibility aliases for one release window, or keep this as a hard break only?

openspec/changes/archive/2026-03-01-rename-runtime-driver-and-node-runtime/proposal.md

@@ -0,0 +1,31 @@
+## Why
+
+The public naming around Node runtime orchestration and driver contracts was still mixed between generic and sandbox-specific terms. Aligning names to `NodeRuntime` and `RuntimeDriver` makes ownership clearer and matches the current architecture split (`NodeRuntime` facade over driver-owned execution internals).
+
+## What Changes
+
+- **BREAKING**: Rename `NodeProcess` to `NodeRuntime` and `NodeProcessOptions` to `NodeRuntimeOptions` in the `secure-exec` public API.
+- **BREAKING**: Rename `SandboxDriver` to `RuntimeDriver` in public and internal driver-facing type contracts.
+- Rename `packages/secure-exec/src/driver-types.ts` to `packages/secure-exec/src/runtime-driver.ts` and update re-exports from `types.ts`.
+- Update tests/examples/docs/spec references to the new names.
+
+## Capabilities
+
+### New Capabilities
+- None.
+
+### Modified Capabilities
+- `node-runtime`: rename runtime facade and driver contract terms from `NodeProcess`/`SandboxDriver` to `NodeRuntime`/`RuntimeDriver`.
+- `node-permissions`: update permission scenarios to reference `NodeRuntime` construction semantics.
+
+## Impact
+
+- `packages/secure-exec/src/index.ts`
+- `packages/secure-exec/src/runtime-driver.ts`
+- `packages/secure-exec/src/types.ts`
+- `packages/secure-exec/src/node/driver.ts`
+- `packages/secure-exec/tests/*` (renamed helper/type usages)
+- `examples/hono/*`, `examples/just-bash/*`
+- `openspec/specs/node-runtime/spec.md`
+- `openspec/specs/node-permissions/spec.md`
+- `docs-internal/arch/overview.md`

openspec/changes/archive/2026-03-01-rename-runtime-driver-and-node-runtime/specs/node-permissions/spec.md

@@ -0,0 +1,19 @@
+## MODIFIED Requirements
+
+### Requirement: allowAll permission helper
+The system SHALL export an `allowAll` constant of type `Permissions` where every domain checker (`fs`, `network`, `childProcess`, `env`) returns `{ allow: true }`.
+
+#### Scenario: Runtime created with allowAll permits all operations
+- **WHEN** a `NodeRuntime` is created with `permissions: allowAll` and a filesystem adapter
+- **THEN** all filesystem operations SHALL succeed without `EACCES` errors
+
+#### Scenario: allowAll is a valid Permissions object
+- **WHEN** `allowAll` is assigned to a variable of type `Permissions`
+- **THEN** it SHALL compile without type errors
+
+### Requirement: Per-domain permission helpers
+The system SHALL export per-domain allow helpers: `allowAllFs`, `allowAllNetwork`, `allowAllChildProcess`, `allowAllEnv`. Each SHALL be a partial `Permissions` object containing only the corresponding domain checker returning `{ allow: true }`.
+
+#### Scenario: Compose per-domain helpers for selective access
+- **WHEN** a `NodeRuntime` is created with `permissions: { ...allowAllFs, ...allowAllNetwork }` and both filesystem and network adapters
+- **THEN** filesystem and network operations SHALL succeed, while child-process and env operations SHALL throw `EACCES`

openspec/changes/archive/2026-03-01-rename-runtime-driver-and-node-runtime/specs/node-runtime/spec.md

@@ -0,0 +1,43 @@
+## MODIFIED Requirements
+
+### Requirement: Unified Sandbox Execution Interface
+The project SHALL provide a stable Node sandbox execution interface, with `NodeRuntime` 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 `NodeRuntime` 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. `NodeRuntime` construction SHALL require a driver.
+
+#### 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: 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