feat(secure-exec): add python runtime and unify integration suites

Author: NathanFlurry

CLAUDE.md

@@ -8,6 +8,7 @@
 - always add or update tests that cover plausible exploit/abuse paths introduced by each feature or behavior change
 - treat host memory buildup and CPU amplification as critical risks; avoid unbounded buffering/work (for example, default in-memory log buffering)
 - check GitHub Actions test/typecheck status per commit to identify when a failure first appeared
+- do not use `contract` in test filenames; use names like `suite`, `behavior`, `parity`, `integration`, or `policy` instead
 
 ## Terminology
 

docs-internal/arch/overview.md

@@ -1,23 +1,24 @@
 # Architecture Overview
 
 ```
-NodeRuntime
-  → SystemDriver + RuntimeDriverFactory
-  → NodeExecutionDriver (node target) | BrowserRuntimeDriver + Worker runtime (browser target)
+NodeRuntime | PythonRuntime
+  → SystemDriver + NodeRuntimeDriverFactory | PythonRuntimeDriverFactory
+  → NodeExecutionDriver (node target) | BrowserRuntimeDriver + Worker runtime (browser target) | PyodideRuntimeDriver + Worker runtime (python target)
 ```
 
-## NodeRuntime
+## NodeRuntime / PythonRuntime
 
-`src/index.ts`
+`src/runtime.ts`, `src/python-runtime.ts`
 
-Public API. Thin facade that delegates orchestration to a runtime driver.
+Public APIs. Thin facades that delegate orchestration to runtime drivers.
 
-- `run(code)` — execute as module, get exports back
+- `NodeRuntime.run(code)` — execute JS module, get exports back
+- `PythonRuntime.run(code)` — execute Python and return structured value/global wrapper
 - `exec(code)` — execute as script, get exit code/error contract
 - `dispose()` / `terminate()`
 - Requires both:
   - `systemDriver` for runtime capabilities/config
-  - `runtimeDriverFactory` for runtime-driver construction
+  - runtime-driver factory for runtime-driver construction
 
 ## SystemDriver
 
@@ -30,7 +31,7 @@ Config object that bundles what the sandbox can access. Deny-by-default.
 - `commandExecutor` — child processes
 - `permissions` — per-adapter allow/deny checks
 
-## RuntimeDriverFactory
+## NodeRuntimeDriverFactory / PythonRuntimeDriverFactory
 
 Factory abstraction for constructing runtime drivers from normalized runtime options.
 
@@ -74,6 +75,15 @@ Factory that builds a browser-backed `RuntimeDriverFactory`.
 - Constructs `BrowserRuntimeDriver` instances
 - Owns worker URL/runtime-driver creation options
 
+### createPyodideRuntimeDriverFactory()
+
+`src/python/driver.ts`
+
+Factory that builds a Python-backed `PythonRuntimeDriverFactory`.
+
+- Constructs `PyodideRuntimeDriver` instances
+- Owns Pyodide worker bootstrap and runtime-driver creation options
+
 ## NodeExecutionDriver
 
 `src/node/execution-driver.ts`
@@ -107,6 +117,18 @@ Worker-side runtime implementation used by the browser runtime driver.
 - Uses permission-aware filesystem/network adapters in the worker context
 - Preserves deterministic unsupported-operation contracts (for example DNS gaps)
 
+## PyodideRuntimeDriver
+
+`src/python/driver.ts`
+
+Python execution driver that owns a Node worker running Pyodide.
+
+- Loads Pyodide once per runtime instance and keeps interpreter state warm across runs
+- Dispatches `run`/`exec` requests and correlates responses by request ID
+- Streams stdio events to host hooks without runtime-managed output buffering
+- Uses worker-to-host RPC for permission-wrapped filesystem/network access through `SystemDriver`
+- Restarts worker state on execution timeout to preserve deterministic recovery behavior
+
 ## ModuleAccessFileSystem
 
 `src/node/module-access.ts`

docs-internal/friction.md

@@ -1,5 +1,16 @@
 # Sandboxed Node Friction Log
 
+## 2026-03-03
+
+1. **[resolved]** Python runtime contract split needed explicit cross-runtime `exec()` parity and warm-state guardrails.
+   - Symptom: introducing Python execution risked mixing Node-only runtime-driver contracts into Python APIs and drifting `exec()` timeout/error semantics across runtimes.
+   - Fix: split runtime-driver interfaces into Node/Python contracts, added `PythonRuntime` + `PyodideRuntimeDriver`, and enforced a shared host-facing `exec()` result contract.
+   - Compatibility trade-off: `PythonRuntime` instances are intentionally warm/shared per instance; callers needing fresh interpreter state must create/terminate runtime instances explicitly.
+2. **[resolved]** Python package installation/loading pathways were intentionally out-of-scope for the first Python runtime increment.
+   - Symptom: enabling package installation in the same change as the core runtime-driver split would widen attack surface and blur permission policy scope.
+   - Fix: Python package install/load pathways now fail deterministically with `ERR_PYTHON_PACKAGE_INSTALL_UNSUPPORTED`.
+   - Follow-up: define explicit package governance and permission policy before enabling runtime package install/load capabilities.
+
 ## 2026-03-02
 
 1. **[resolved]** Browser runtime execution was intentionally disabled during runtime-driver boundary refactor.
@@ -41,7 +52,7 @@
 
 2. **[resolved]** Bridge/global type contracts drifted across host wiring, bridge modules, and isolate-runtime declarations.
    - Symptom: host injection keys, bridge global declarations, and isolate-runtime global types were defined ad hoc in multiple files, leaving boundary typing inconsistent and prone to regressions.
-   - Fix: added canonical shared bridge contract definitions in `packages/secure-exec/src/shared/bridge-contract.ts`, migrated bridge modules and `src/index.ts` wiring to shared keys/types, coupled isolate-runtime declarations to shared types via type-only imports, and added `packages/secure-exec/tests/bridge-contract.test.ts` to enforce key/type registry consistency.
+   - Fix: added canonical shared bridge contract definitions in `packages/secure-exec/src/shared/bridge-contract.ts`, migrated bridge modules and `src/index.ts` wiring to shared keys/types, coupled isolate-runtime declarations to shared types via type-only imports, and added `packages/secure-exec/tests/bridge-registry-policy.test.ts` to enforce key/type registry consistency.
 
 ## 2026-02-27
 

openspec/changes/add-python-runtime-driver/.openspec.yaml

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

openspec/changes/add-python-runtime-driver/design.md

@@ -0,0 +1,72 @@
+## Context
+
+`secure-exec` runtime architecture is currently optimized for Node-oriented execution drivers and contracts. The current runtime driver naming and shape make Python support ambiguous, while host-facing orchestration needs a stable `exec()` contract across runtimes.
+
+This change introduces an explicit Python runtime path using a Pyodide-backed driver while keeping `SystemDriver` generic and preserving existing permission enforcement behavior. The design must keep warm runtime lifecycle semantics and avoid memory/CPU amplification regressions.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Split runtime-driver interfaces into runtime-specific contracts (`NodeRuntimeDriver`, `PythonRuntimeDriver`) while preserving a shared execution result contract for `exec()`.
+- Add `PythonRuntime` as a user-facing API and implement a concrete Pyodide-backed Python driver.
+- Keep `SystemDriver` runtime-agnostic and reuse existing permissions (`fs`, `network`, `childProcess`, `env`) for Python execution.
+- Define a generic Python `run()` result wrapper that does not expose raw Pyodide-specific objects.
+- Keep warm-runtime behavior for Python execution on a single runtime instance.
+- Add explicit abuse-path coverage (high-volume output and timeout paths).
+
+**Non-Goals:**
+- Dynamic runtime package installation/loading (`micropip`, import-triggered package install) behavior.
+- Non-Pyodide Python backends (for example host subprocess CPython).
+- Full parity between Node `run()` and Python `run()` result semantics.
+
+## Decisions
+
+1. Introduce runtime-specific driver interfaces with a shared execution base contract.
+- Decision: Define separate `NodeRuntimeDriver` and `PythonRuntimeDriver` interfaces, plus a shared `exec` lifecycle contract (`exec`, `dispose`, `terminate`).
+- Rationale: Prevent Node-only and Python-only concerns from leaking into each other while keeping host orchestration uniform.
+- Alternative considered: Keep one generic runtime-driver interface with optional runtime-specific methods. Rejected because it grows ambiguous and weakens type-level guarantees.
+
+2. Keep `SystemDriver` capability-owned and runtime-neutral.
+- Decision: `SystemDriver` remains the single capability/permission boundary for both runtimes.
+- Rationale: Preserves deny-by-default behavior and avoids runtime-specific capability duplication.
+- Alternative considered: Add Python-only capability adapters to `SystemDriver`. Rejected for now to avoid premature surface expansion.
+
+3. Standardize `exec()` parity across Node and Python runtimes.
+- Decision: Node and Python `exec()` return the same base result semantics (`code`, `errorMessage`, timeout/cancel expectations).
+- Rationale: Enables runtime-agnostic host orchestration and simpler control planes.
+- Alternative considered: Runtime-specific `exec()` contracts. Rejected due to host branching and governance complexity.
+
+4. Define Python `run()` as a generic structured wrapper.
+- Decision: `PythonRuntime.run()` returns a structured Python run result wrapper (for example value plus optional selected bindings), not raw Pyodide proxies.
+- Rationale: Keeps API portable and avoids runtime-specific memory/lifecycle leaks through public contracts.
+- Alternative considered: Return raw Pyodide values/proxies. Rejected because it couples API consumers to one backend and increases leak risk.
+
+5. Keep Python runtime warm by default per instance.
+- Decision: Consecutive Python executions on the same `PythonRuntime` share runtime state unless explicitly disposed/terminated.
+- Rationale: Matches current runtime lifecycle expectations and improves performance.
+- Alternative considered: Fresh interpreter per execution. Rejected for now due to startup overhead and changed semantics.
+
+6. Keep package installation/loading out of scope for this change.
+- Decision: Python runtime package installation/loading APIs are not enabled in this change and MUST fail deterministically when invoked.
+- Rationale: Reduces initial attack surface and keeps scope focused on core runtime contracts.
+- Alternative considered: Enable package loading behind permissions in v1. Rejected to avoid mixing supply-chain policy with foundational runtime split.
+
+## Risks / Trade-offs
+
+- [Risk] Warm Python state can leak data across executions on the same instance. → Mitigation: document lifecycle clearly and provide deterministic `dispose`/`terminate` behavior.
+- [Risk] High-volume Python stdout/stderr can amplify host memory/CPU if buffered. → Mitigation: enforce streaming-only output behavior and add exploit-oriented high-volume tests.
+- [Risk] Timeout/cancellation semantics can drift between Node and Python drivers. → Mitigation: codify shared `exec()` parity requirements and cross-runtime contract suites.
+- [Risk] API overfitting to Pyodide backend details. → Mitigation: keep Python runtime public contracts backend-neutral and block direct Pyodide proxy exposure.
+
+## Migration Plan
+
+1. Add new runtime-driver interfaces and type aliases with backwards-compatible export strategy where possible.
+2. Introduce `PythonRuntime` and `PyodideRuntimeDriver` behind additive API exports.
+3. Update Node runtime wiring to use renamed Node-specific driver interface without behavior regressions.
+4. Add shared/runtime-specific contract tests and abuse-path regressions.
+5. Update architecture/docs to include Python runtime components and contracts.
+
+## Open Questions
+
+- Do we need a first-class explicit reset API for warm Python runtime instances in this change or follow-up?
+- Should timeout error text be strictly identical across runtimes or only semantically equivalent under shared `ExecResult` fields?

openspec/changes/add-python-runtime-driver/proposal.md

@@ -0,0 +1,28 @@
+## Why
+
+The runtime stack is currently Node-centric and cannot host Python execution without leaking Node assumptions into cross-runtime APIs. We need first-class Python runtime support now so hosts can run Python code with the same safety and permission model used by existing system drivers.
+
+## What Changes
+
+- Add a new Python runtime surface (`PythonRuntime`) with a dedicated driver interface and a concrete Pyodide-based driver implementation.
+- Split runtime driver contracts so Node and Python use separate interfaces (`NodeRuntimeDriver` and `PythonRuntimeDriver`) while preserving shared execution-result semantics for `exec()`.
+- Keep `SystemDriver` runtime-agnostic and require Python execution to use the same filesystem/network/child-process/env permission gates already enforced by system drivers.
+- Define Python `run()` contract as a runtime-neutral structured wrapper (not raw Pyodide-specific objects).
+- Keep warm-runtime behavior for Python execution, matching current Node runtime lifecycle expectations.
+- Explicitly keep runtime package installation/loading (`micropip`, import-triggered package install) out of scope for this change.
+
+## Capabilities
+
+### New Capabilities
+- `python-runtime`: Python runtime API and driver contracts, including Pyodide-backed execution behavior and Python-specific run semantics.
+
+### Modified Capabilities
+- `node-runtime`: Runtime-driver architecture and naming/contracts updated to split Node and Python runtime drivers while preserving Node behavior.
+- `compatibility-governance`: Runtime-driver test governance expanded so shared `exec()` parity and Python abuse/safety regressions are covered.
+
+## Impact
+
+- Affected code: runtime contracts/types, runtime API exports, driver factories, and new Python runtime/driver modules.
+- Affected tests: new Python runtime-driver contract tests and cross-runtime `exec()` parity tests, plus abuse-path regressions for output/memory/CPU amplification.
+- Affected docs/specs: architecture overview and runtime specs will add Python runtime components and clarify shared-vs-runtime-specific contracts.
+- Dependencies: introduces Pyodide runtime integration for the Python driver implementation.

openspec/changes/add-python-runtime-driver/specs/compatibility-governance/spec.md

@@ -0,0 +1,30 @@
+## ADDED Requirements
+
+### Requirement: Python Runtime Driver Changes MUST Validate Shared Runtime Contracts
+Any change that introduces or modifies Python runtime-driver behavior MUST validate shared execution contracts and Python-specific runtime-driver suites.
+
+#### Scenario: Python runtime contract change triggers shared and Python runtime-driver suites
+- **WHEN** a change modifies Python runtime contracts or Python runtime-driver behavior under `packages/secure-exec/src/python/**`, `src/runtime.ts`, or shared runtime driver types
+- **THEN** the change MUST run `pnpm --filter secure-exec vitest --run tests/test-suite.test.ts tests/test-suite-python.test.ts` and `pnpm --filter secure-exec vitest --run tests/runtime-driver/python.test.ts`
+
+#### Scenario: Python execution behavior change triggers Python exec behavior suites
+- **WHEN** a change modifies Python execution behavior or Python execution suites under `packages/secure-exec/tests/test-suite/`
+- **THEN** the change MUST run `pnpm --filter secure-exec vitest --run tests/test-suite-python.test.ts`
+
+### Requirement: Cross-Runtime Exec Parity Must Be Regression-Tested
+Changes that affect shared execution result semantics SHALL preserve Node/Python `exec()` parity for host-facing result contracts.
+
+#### Scenario: Shared exec result semantics change
+- **WHEN** a change modifies shared execution result fields or timeout/error contract behavior
+- **THEN** the change MUST include or update tests that verify Node and Python runtimes return the same base `exec()` contract semantics
+
+### Requirement: Python Runtime Changes MUST Include Abuse-Path Coverage
+Python runtime changes SHALL include exploit-oriented regression coverage for memory and CPU amplification paths.
+
+#### Scenario: High-volume stdout/stderr path is modified
+- **WHEN** Python runtime logging/stdio handling changes
+- **THEN** tests MUST verify high-volume output does not create unbounded host-memory accumulation
+
+#### Scenario: Timeout enforcement path is modified
+- **WHEN** Python runtime CPU limit enforcement behavior changes
+- **THEN** tests MUST verify deterministic timeout contract behavior and runtime recovery expectations

openspec/changes/add-python-runtime-driver/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 `NodeRuntimeDriver` contract.
+
+#### Scenario: Node runtime uses configured adapters with explicit Node runtime driver
+- **WHEN** `NodeRuntime` is created with a `SystemDriver` that defines filesystem, network, and command-execution adapters and with a `NodeRuntimeDriver`
+- **THEN** sandboxed operations MUST route through those adapters for capability access and execution MUST be created through the provided Node runtime driver contract
+
+#### 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