refactor(secure-exec): remove legacy output buffers and sync specs

Author: NathanFlurry

docs-internal/friction/secure-exec.md

@@ -5,7 +5,8 @@
 1. **[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.
-   - Compatibility trade-off: `exec()`/`run()` no longer mirror Node stdout/stderr buffering by default; consumers that need console output must opt into hook-based streaming.
+   - 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.
 2. **[resolved]** Node module loading depended on allowlist projection setup and split filesystem paths.
    - Symptom: sandbox `node_modules` availability varied by `moduleAccess.allowPackages` setup and base filesystem mount location, which added resolver complexity and setup fragility.
    - Fix: Node driver now always composes a read-only `/app/node_modules` overlay from `<cwd>/node_modules`, even without a base filesystem adapter. Overlay reads are canonical-path scoped to `<cwd>/node_modules`; writes/mutations remain denied; `.node` native addons are rejected.

docs/node-compatability.mdx

@@ -56,7 +56,8 @@ Unsupported modules use: `"<module> is not supported in sandbox"`.
 ## Logging Behavior
 
 - `console.log`/`warn`/`error` are supported and serialize arguments with circular-safe bounded formatting.
-- By default, secure-exec drops console emissions instead of buffering them into `exec()`/`run()` result `stdout`/`stderr`.
+- `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.
 
 ## Node-Modules Overlay Behavior

docs/quickstart.mdx

@@ -14,10 +14,17 @@ description: Get secure-exec running from TypeScript in a few minutes.
     import { NodeProcess, createNodeDriver } from "secure-exec";
 
     const proc = new NodeProcess({ driver: createNodeDriver({}) });
-    const result = await proc.exec("console.log('hello from secure-exec')");
-    console.log(result.stdout);
+    const logs: string[] = [];
+    const result = await proc.exec("console.log('hello from secure-exec')", {
+      onConsoleLog: (event) => {
+        logs.push(`[${event.channel}] ${event.message}`);
+      },
+    });
+    if (result.errorMessage) {
+      throw new Error(result.errorMessage);
+    }
+    console.log(logs.join("\n"));
     await proc.dispose();
     ```
   </Step>
 </Steps>
-

docs/security-model.mdx

@@ -73,13 +73,13 @@ Setting `timingMitigation: "off"` gives you normal advancing clocks but weaker s
 
 Two controls prevent runaway execution:
 
-- **`cpuTimeLimitMs`** — CPU time budget for the runtime. When exceeded, the process exits with code `124` and stderr includes `CPU time limit exceeded`.
+- **`cpuTimeLimitMs`** — CPU time budget for the runtime. When exceeded, the process exits with code `124` and `errorMessage` includes `CPU time limit exceeded`.
 - **`memoryLimit`** — Isolate memory cap in MB (default `128`).
 
 The bridge also enforces isolate-boundary payload limits so oversized base64 file transfers and oversized isolate-originated JSON payloads are rejected deterministically with `ERR_SANDBOX_PAYLOAD_TOO_LARGE` instead of exhausting host memory. Hosts can tune these limits within bounded safe ranges, but cannot disable enforcement.
 
 ## Logging Contract
 
-- Console output is **not buffered** into runtime-managed `stdout`/`stderr` by default.
+- 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.
 - This avoids implicit host-memory growth from untrusted high-volume logging.

openspec/changes/archive/2026-03-01-remove-legacy-output-surfaces/.openspec.yaml

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

openspec/changes/archive/2026-03-01-remove-legacy-output-surfaces/design.md

@@ -0,0 +1,65 @@
+## Context
+
+`secure-exec` runtime behavior was intentionally changed to drop console output by default and stream logs via `onConsoleLog`, but the public result types still expose legacy `stdout`/`stderr` fields. The repository also has stale artifacts tied to old behavior:
+
+- `packages/secure-exec/tests/logging-load.test.ts` still expects multi-megabyte `result.stdout` buffering and currently fails.
+- `docs/quickstart.mdx` still demonstrates `console.log(result.stdout)`.
+- strict unused-symbol scan (`tsc --noEmit --noUnusedLocals --noUnusedParameters`) reports dead symbols in runtime/bridge modules.
+
+This mismatch increases maintenance cost, obscures intended behavior, and leaves unnecessary memory-amplification paths.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Remove legacy execution-result output capture fields from runtime APIs.
+- Keep output delivery hook-only and non-buffering by default across runtimes.
+- Delete confirmed dead symbols/properties/methods that no longer participate in runtime behavior.
+- Replace stale logging tests/docs with exploit-oriented no-buffer assertions.
+
+**Non-Goals:**
+- Redesign child-process API semantics beyond removal of dead placeholders.
+- Introduce a new persistent logging backend or retention store.
+- Change project-matrix pass/fail fixture policy.
+
+## Decisions
+
+1. Remove `stdout`/`stderr` from `ExecResult` and `RunResult` (breaking change).
+- Rationale: current contract is misleading and encourages polling result buffers that should stay absent for safety.
+- Alternative considered: keep empty fields indefinitely for compatibility. Rejected because it preserves ambiguous API and stale usage patterns.
+
+2. Preserve deterministic failure visibility with explicit non-buffered error metadata.
+- Rationale: callers still need failure reasons without reopening unbounded output capture.
+- Alternative considered: throw for all failures and remove result metadata. Rejected to avoid broad behavioral churn in existing `exec` flow.
+
+3. Remove dead symbols found by strict compiler scan and manual bridge review.
+- Targets include unused flags in `NodeProcess`, dead helper/types in `bridge/fs.ts` and `bridge/module.ts`, and unused imports in permission wrappers.
+- Alternative considered: keep symbols as comments or `_` placeholders. Rejected because these are not compatibility contracts and add maintenance noise.
+
+4. Replace legacy logging-load test with exploit-focused regression tests.
+- Rationale: testing should enforce that high-volume logs do not accumulate in runtime-managed buffers.
+- Alternative considered: delete stale tests without replacement. Rejected because we would lose regression coverage for a known resource-exhaustion vector.
+
+## Risks / Trade-offs
+
+- [Consumer breakage from result type changes] -> Mitigation: mark breaking in proposal/specs, update type tests, provide migration examples using `onConsoleLog`.
+- [Loss of convenience for callers that relied on `result.stderr`] -> Mitigation: provide explicit bounded error metadata in results and updated docs.
+- [Node/browser runtime behavior drift] -> Mitigation: align contracts in shared API types and add parity tests for logging defaults.
+- [Over-removal of symbols that are intentionally reserved] -> Mitigation: limit removals to symbols proven unused by compiler diagnostics or direct file-scope analysis.
+
+## Migration Plan
+
+1. Update shared result types and runtime return shapes.
+2. Refactor Node and browser execution pipelines to remove legacy `stdout`/`stderr` result plumbing.
+3. Update tests:
+- remove/replace stale buffering assertions
+- add exploit regression checks for high-volume logs
+- update type tests for new result contract
+4. Update docs (`quickstart`, `node-compatability`, `security-model`, friction notes).
+5. Run focused checks (`check-types`, targeted vitest files) before merge.
+
+Rollback: revert result-type and runtime-shape commits as one unit; keep dead-code removals isolated in separate commits if split rollout is needed.
+
+## Open Questions
+
+- Should runtime failure metadata be `error?: { message: string; kind?: string }` or a flat `errorMessage?: string`?
+- Should browser worker expose the same `onConsoleLog` hook API in this change or in a follow-up?

openspec/changes/archive/2026-03-01-remove-legacy-output-surfaces/proposal.md

@@ -0,0 +1,27 @@
+## Why
+
+Recent runtime changes made console output drop-by-default with optional streaming hooks, but several legacy output-capture surfaces and dead symbols remain. This creates confusing API/documentation contracts, stale tests, and unnecessary host-memory risk from leftover buffering paths.
+
+## What Changes
+
+- **BREAKING**: remove `stdout`/`stderr` fields from `ExecResult` and `RunResult`; expose only deterministic execution status (`code`, `exports` for `run`) plus explicit error metadata for runtime failures.
+- Keep console output delivery exclusively through `onConsoleLog` streaming hooks; no runtime-managed result buffering in Node or browser runtimes.
+- Remove confirmed dead/legacy symbols found by strict unused checks (unused fields, helpers, and type aliases) in runtime/bridge sources.
+- Replace stale log-buffering regression test with exploit-oriented tests that assert no accumulation under high-volume logging.
+- Update quickstart/security/compat docs to remove `result.stdout` examples and show hook-based log consumption.
+
+## Capabilities
+
+### New Capabilities
+- `execution-result-minimal-contract`: Define minimal non-buffered execution result shape and migration expectations.
+
+### Modified Capabilities
+- `node-runtime`: Runtime result contract and logging behavior wording updated to remove legacy `stdout`/`stderr` result fields.
+- `documentation-site`: Quickstart/runtime examples updated to match hook-based logging contract.
+- `compatibility-governance`: Ensure required exploit-focused tests cover memory-amplification regressions for logging/output paths.
+
+## Impact
+
+- Affected code: `packages/secure-exec/src/shared/api-types.ts`, `packages/secure-exec/src/index.ts`, `packages/secure-exec/src/execution.ts`, browser runtime files, bridge cleanup sites (`bridge/fs.ts`, `bridge/module.ts`, `shared/permissions.ts`, `bridge/child-process.ts`), tests, docs.
+- API impact: Type-level and runtime response shape changes for `exec()`/`run()` consumers.
+- Governance impact: stronger regression coverage around memory/CPU amplification vectors tied to output handling.

openspec/changes/archive/2026-03-01-remove-legacy-output-surfaces/specs/compatibility-governance/spec.md

@@ -0,0 +1,16 @@
+## MODIFIED Requirements
+
+### Requirement: Logging Capture Contract Changes MUST Update Compatibility And Security Docs
+Any change that introduces or modifies runtime log-capture defaults or hook-based logging behavior MUST update compatibility/friction/security documentation in the same change and MUST include exploit-oriented regression tests for host resource amplification.
+
+#### Scenario: Runtime switches default logging behavior
+- **WHEN** runtime logging defaults change (for example from buffered capture to log-drop)
+- **THEN** `docs-internal/friction/secure-exec.md` MUST document the compatibility impact and resource-exhaustion rationale in the same change
+
+#### Scenario: Runtime introduces or changes log-stream hook behavior
+- **WHEN** runtime log-stream hook contract changes (event shape, ordering semantics, or failure behavior)
+- **THEN** `docs/security-model.mdx` MUST describe trust-boundary and resource-consumption implications and `docs/node-compatability.mdx` MUST reflect user-visible behavior changes where applicable
+
+#### Scenario: Logging changes include exploit regression coverage
+- **WHEN** logging/output behavior is changed in runtime or bridge paths
+- **THEN** the same change MUST include tests that assert high-volume log emission does not create unbounded host-memory accumulation

openspec/changes/archive/2026-03-01-remove-legacy-output-surfaces/specs/documentation-site/spec.md

@@ -0,0 +1,16 @@
+## MODIFIED Requirements
+
+### Requirement: Quickstart Uses Steps With Runnable Example
+The Quickstart page SHALL present onboarding steps using Mintlify `<Steps>` and SHALL include at least one basic runnable example that verifies setup success using the current runtime logging contract.
+
+#### Scenario: Steps component structures onboarding
+- **WHEN** the Quickstart page is rendered
+- **THEN** the page MUST contain a `<Steps>` block with ordered setup actions
+
+#### Scenario: Quickstart includes basic verification example
+- **WHEN** a user follows the Quickstart page
+- **THEN** the page MUST provide at least one concrete command example and expected successful outcome text
+
+#### Scenario: Quickstart does not rely on legacy buffered output fields
+- **WHEN** Quickstart demonstrates how to read execution logs
+- **THEN** it MUST use hook-based log streaming examples and MUST NOT instruct users to read `result.stdout` or `result.stderr`

openspec/changes/archive/2026-03-01-remove-legacy-output-surfaces/specs/execution-result-minimal-contract/spec.md

@@ -0,0 +1,19 @@
+## ADDED Requirements
+
+### Requirement: Execution Results MUST Exclude Buffered Output Fields
+The runtime SHALL return minimal execution results that do not include runtime-managed `stdout` or `stderr` capture fields.
+
+#### Scenario: Exec result contains status without output buffers
+- **WHEN** `NodeProcess.exec()` completes in default logging mode
+- **THEN** the returned result MUST include execution status fields and MUST NOT include `stdout`/`stderr` properties
+
+#### Scenario: Run result contains exports without output buffers
+- **WHEN** `NodeProcess.run()` completes and returns module exports
+- **THEN** the returned result MUST include `code` and `exports` semantics and MUST NOT include `stdout`/`stderr` properties
+
+### Requirement: Failure Details MUST Be Exposed Without Log Buffer Retention
+The runtime SHALL expose deterministic failure metadata without retaining unbounded per-execution log buffers.
+
+#### Scenario: Runtime error remains observable without stderr capture
+- **WHEN** execution fails due to runtime error
+- **THEN** callers MUST receive deterministic failure metadata sufficient for debugging without requiring buffered `stderr` output capture