feat: US-018 - Update turbo, CI, contracts, and architecture docs for final state

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: NathanFlurry

.agent/contracts/compatibility-governance.md

@@ -8,25 +8,25 @@ Changes that add, remove, or materially alter TypeScript compile/typecheck behav
 
 #### Scenario: Core runtime TypeScript handling changes
 - **WHEN** the core runtime adds or removes implicit TypeScript preprocessing behavior
-- **THEN** `docs/quickstart.mdx`, `docs/api-reference.mdx`, `docs/runtimes/node.mdx`, `docs/node-compatability.mdx`, `docs-internal/arch/overview.md`, and `docs-internal/friction.md` MUST be updated in the same change
+- **THEN** `docs/quickstart.mdx`, `docs/api-reference.mdx`, `docs/runtimes/node.mdx`, `docs/nodejs-compatibility.mdx`, `docs-internal/arch/overview.md`, and `docs-internal/friction.md` MUST be updated in the same change
 
 #### Scenario: Companion TypeScript tooling API changes
 - **WHEN** the public API of the companion TypeScript tooling package changes
 - **THEN** `docs/quickstart.mdx` and `docs/api-reference.mdx` MUST be updated in the same change so project/source helper semantics remain accurate
 
 ### Requirement: Maintain Node Stdlib Compatibility Matrix
-Changes affecting bridged or polyfilled Node APIs MUST keep `docs/node-compatability.mdx` synchronized with the actual runtime surface, including supported, limited, and unsupported modules/APIs. Every module entry in the matrix MUST include an explicit support-tier classification (Bridge, Polyfill, Stub, Deferred, or Unsupported) as defined by the `node-stdlib` spec. The page MUST include a top-of-page target Node version statement.
+Changes affecting bridged or polyfilled Node APIs MUST keep `docs/nodejs-compatibility.mdx` synchronized with the actual runtime surface, including supported, limited, and unsupported modules/APIs. Every module entry in the matrix MUST include an explicit support-tier classification (Bridge, Polyfill, Stub, Deferred, or Unsupported) as defined by the `node-stdlib` spec. The page MUST include a top-of-page target Node version statement.
 
 #### Scenario: Bridge API surface changes
 - **WHEN** a change adds, removes, or materially alters bridged Node API behavior
-- **THEN** the compatibility matrix page at `docs/node-compatability.mdx` MUST be updated in the same change to reflect the new runtime contract
+- **THEN** the compatibility matrix page at `docs/nodejs-compatibility.mdx` MUST be updated in the same change to reflect the new runtime contract
 
 #### Scenario: Legacy internal matrix path appears anywhere in repository docs/spec sources
 - **WHEN** a repository document or spec source references the legacy internal stdlib compatibility document
-- **THEN** the reference MUST be replaced with `docs/node-compatability.mdx` before the change is considered complete
+- **THEN** the reference MUST be replaced with `docs/nodejs-compatibility.mdx` before the change is considered complete
 
 #### Scenario: Target Node version callout is missing
-- **WHEN** `docs/node-compatability.mdx` is updated
+- **WHEN** `docs/nodejs-compatibility.mdx` is updated
 - **THEN** the page MUST retain an explicit target Node version statement at the top
 
 ### Requirement: Node Compatibility Target Version Tracks Test Type Baseline
@@ -38,7 +38,7 @@ The runtime compatibility target MUST align with the `@types/node` package major
 
 #### Scenario: `@types/node` target major is upgraded
 - **WHEN** the workspace intentionally upgrades `@types/node` to a new major version used by secure-exec validation
-- **THEN** the same change MUST update `docs/node-compatability.mdx` and related compatibility-governance references to the new target Node major line
+- **THEN** the same change MUST update `docs/nodejs-compatibility.mdx` and related compatibility-governance references to the new target Node major line
 
 #### Scenario: Compatibility target is documented
 - **WHEN** compatibility requirements or docs declare a target Node version
@@ -67,10 +67,10 @@ Unexpected issues, workarounds, and integration friction encountered during secu
 - **THEN** its log entry MUST be updated to indicate resolution and summarize the fix
 
 ### Requirement: Run Bridge Type Conformance Tests After Bridge Changes
-Any change to files under `packages/secure-exec-core/src/bridge` MUST run bridge type conformance checks via `pnpm run check-types:test` in `packages/secure-exec` before completion.
+Any change to files under `packages/secure-exec-nodejs/src/bridge` MUST run bridge type conformance checks via `pnpm run check-types:test` in `packages/secure-exec` before completion.
 
 #### Scenario: Bridge source file is modified
-- **WHEN** a commit modifies one or more files in `packages/secure-exec-core/src/bridge`
+- **WHEN** a commit modifies one or more files in `packages/secure-exec-nodejs/src/bridge`
 - **THEN** `pnpm run check-types:test` MUST be executed and failures MUST be addressed before the change is considered complete
 
 ### Requirement: Compatibility Project Matrix Uses Black-Box Node Fixtures
@@ -251,7 +251,7 @@ Any change that introduces or modifies runtime log-capture defaults or hook-base
 
 #### 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
+- **THEN** `docs/security-model.mdx` MUST describe trust-boundary and resource-consumption implications and `docs/nodejs-compatibility.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

.agent/contracts/documentation-site.md

@@ -8,11 +8,11 @@ The documentation site SHALL expose a core navigation set that includes Quicksta
 
 #### Scenario: Docs configuration defines required core pages
 - **WHEN** the docs configuration is loaded
-- **THEN** navigation MUST include `quickstart`, `security-model`, and `node-compatability` as available documentation pages
+- **THEN** navigation MUST include `quickstart`, `security-model`, and `nodejs-compatibility` as available documentation pages
 
 #### Scenario: Node compatibility page path is resolvable
 - **WHEN** a user selects the Node Compatibility page from navigation
-- **THEN** the docs site MUST resolve and render `node-compatability.mdx` successfully
+- **THEN** the docs site MUST resolve and render `nodejs-compatibility.mdx` successfully
 
 ### 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.
@@ -30,17 +30,17 @@ The Quickstart page SHALL present onboarding steps using Mintlify `<Steps>` and
 - **THEN** it MUST use hook-based log streaming examples and MUST NOT instruct users to read `result.stdout` or `result.stderr`
 
 ### Requirement: Node Compatibility Page Declares Target Version and Matrix
-The docs site MUST provide `docs/node-compatability.mdx` with an explicit target Node version statement near the top of the page and a clean compatibility matrix table that summarizes module support tier and runtime notes.
+The docs site MUST provide `docs/nodejs-compatibility.mdx` with an explicit target Node version statement near the top of the page and a clean compatibility matrix table that summarizes module support tier and runtime notes.
 
 #### Scenario: Target Node version is visible at top of page
-- **WHEN** `node-compatability.mdx` is rendered
+- **WHEN** `nodejs-compatibility.mdx` is rendered
 - **THEN** users MUST see the targeted Node version before the compatibility matrix content
 
 #### Scenario: Compatibility matrix uses concise tabular format
-- **WHEN** `node-compatability.mdx` is rendered
+- **WHEN** `nodejs-compatibility.mdx` is rendered
 - **THEN** it MUST include a simple table with module/support-tier/status details migrated from the internal compatibility source
 
 #### Scenario: Permission model scope stays at runtime and bridge contract
-- **WHEN** `node-compatability.mdx` documents permission behavior
+- **WHEN** `nodejs-compatibility.mdx` documents permission behavior
 - **THEN** it MUST describe core runtime/bridge permission enforcement and MUST NOT present driver-construction convenience defaults as the canonical security contract
 

.agent/contracts/node-bridge.md

@@ -117,7 +117,7 @@ Bridge-exposed filesystem metadata calls (`exists`, `stat`, and typed directory
 - **THEN** bridge handling MUST return entry type information without a repeated `readDir` probe for each entry
 
 ### Requirement: Bridge Boundary Contracts SHALL Be Defined In A Canonical Shared Type Module
-Bridge global keys and host/isolate boundary type contracts SHALL be defined in one canonical shared type module under `packages/secure-exec-core/src/shared/` and reused across host runtime setup and bridge modules.
+Bridge global keys and host/isolate boundary type contracts SHALL be defined in canonical shared type modules — bridge-contract types in `packages/secure-exec-nodejs/src/bridge-contract.ts` and global-exposure helpers in `packages/secure-exec-core/src/shared/global-exposure.ts` — and reused across host runtime setup and bridge modules.
 
 #### Scenario: Host runtime injects bridge globals
 - **WHEN** host runtime code wires bridge globals into the isolate

.agent/contracts/runtime-driver-test-suite-structure.md

@@ -10,7 +10,7 @@ Secure-exec runtime-driver integration coverage MUST use the canonical filesyste
 - `packages/secure-exec/tests/test-suite/{name}.ts`
 - `packages/secure-exec/tests/exec-driver/{name}.test.ts`
 - `packages/secure-exec/tests/runtime-driver/{name}.test.ts`
-- `packages/kernel/test/{name}.test.ts` (kernel unit tests)
+- `packages/secure-exec-core/test/kernel/{name}.test.ts` (kernel unit tests)
 - `packages/secure-exec/tests/kernel/{name}.test.ts` (kernel cross-runtime integration tests)
 
 #### Scenario: Shared matrix entrypoint exists at canonical path
@@ -48,15 +48,15 @@ Shared suite registration order in the matrix entrypoint MUST be explicit and st
 - **THEN** they MUST be imported and invoked in deterministic source order rather than filesystem discovery
 
 ### Requirement: Kernel Unit Tests SHALL Use MockRuntimeDriver In Kernel Package
-Kernel unit tests that validate kernel subsystem behavior (VFS, FD table, process table, device layer, pipe manager, command registry, permissions) SHALL reside under `packages/kernel/test/` and use MockRuntimeDriver for driver interactions.
+Kernel unit tests that validate kernel subsystem behavior (VFS, FD table, process table, device layer, pipe manager, command registry, permissions) SHALL reside under `packages/secure-exec-core/test/kernel/` and use MockRuntimeDriver for driver interactions.
 
 #### Scenario: Kernel unit tests live in kernel package
 - **WHEN** contributors add or update tests for kernel subsystem behavior
-- **THEN** those tests MUST reside under `packages/kernel/test/` as `*.test.ts` files
+- **THEN** those tests MUST reside under `packages/secure-exec-core/test/kernel/` as `*.test.ts` files
 
 #### Scenario: Kernel unit tests use MockRuntimeDriver
 - **WHEN** kernel unit tests need to validate spawn/exec orchestration or command registration
-- **THEN** they MUST use a MockRuntimeDriver (from `packages/kernel/test/helpers.ts`) that implements the RuntimeDriver interface with controllable behavior, rather than requiring real runtime drivers
+- **THEN** they MUST use a MockRuntimeDriver (from `packages/secure-exec-core/test/kernel/helpers.ts`) that implements the RuntimeDriver interface with controllable behavior, rather than requiring real runtime drivers
 
 #### Scenario: Kernel unit tests validate subsystem invariants independently
 - **WHEN** kernel unit tests validate FD table, process table, pipe manager, or device layer behavior

.github/workflows/ci.yml

@@ -35,7 +35,7 @@ jobs:
           key: wasm-${{ runner.os }}-${{ hashFiles('native/wasmvm/Cargo.lock', 'native/wasmvm/rust-toolchain.toml') }}
 
       - name: Build WASM binary
-        run: cd wasmvm && make wasm
+        run: cd native/wasmvm && make wasm
 
       # --- C toolchain (wasi-sdk + patched sysroot + C test fixtures) ---
       - name: Cache wasi-sdk

docs-internal/arch/overview.md

@@ -1,54 +1,77 @@
 # Architecture Overview
 
 ```
-  NodeRuntime / PythonRuntime
+  Kernel-first API (createKernel + mount + exec)
   packages/secure-exec-core/
+
+  Legacy facade: NodeRuntime (packages/secure-exec/src/runtime.ts)
          │
-    ┌────┴─────┬──────────┐
-    │          │          │
-  Node      Browser    Python
-  packages/ packages/  packages/
-  secure-   secure-    secure-
-  exec-     exec-      exec-
-  node/     browser/   python/
+    ┌────┴─────┬──────────┬──────────┐
+    │          │          │          │
+  Node      Browser    Python    WasmVM
+  packages/ packages/  packages/ packages/
+  secure-   secure-    secure-   secure-
+  exec-     exec-      exec-     exec-
+  nodejs/   browser/   python/   wasmvm/
 
 Package index:
 
   @secure-exec/core        packages/secure-exec-core/
-    Shared types, utilities, bridge, NodeRuntime/PythonRuntime classes,
-    isolate-runtime source, build scripts
+    Kernel (VFS, FD table, process table, device layer, pipes, PTY,
+    command registry, permissions), shared types, utilities,
+    isolate-runtime source, in-memory filesystem
 
   @secure-exec/v8          packages/secure-exec-v8/
     V8 runtime process manager (spawns Rust binary, IPC client,
     session abstraction). MessagePack framing over UDS.
 
   @secure-exec/nodejs      packages/secure-exec-nodejs/
-    Execution driver, bridge-handlers, bridge-loader, module-access overlay,
-    createNodeDriver, createNodeRuntimeDriverFactory
+    Node execution driver, bridge polyfills, bridge-handlers,
+    bridge-loader, module-access overlay, ESM compiler,
+    module resolver, package bundler, kernel runtime driver
+    (createNodeRuntime), createNodeDriver, createNodeRuntimeDriverFactory
 
   @secure-exec/browser     packages/secure-exec-browser/
-    Web Worker execution driver, createBrowserDriver,
+    Web Worker execution driver, browser VFS (InMemoryFileSystem),
+    browser worker adapter, createBrowserDriver,
     createBrowserRuntimeDriverFactory
 
   @secure-exec/python      packages/secure-exec-python/
-    Pyodide execution driver, createPyodideRuntimeDriverFactory
+    Pyodide execution driver, kernel runtime driver
+    (createPythonRuntime), createPyodideRuntimeDriverFactory
+
+  @secure-exec/wasmvm      packages/secure-exec-wasmvm/
+    WasmVM runtime driver (createWasmVmRuntime), WASI polyfill,
+    kernel worker management. WASM binaries in native/wasmvm/target/
 
   @secure-exec/typescript  packages/secure-exec-typescript/
     Optional TypeScript compiler tools (type-checking, compilation)
 
   secure-exec              packages/secure-exec/
-    Barrel re-export layer (re-exports core, node, browser, python)
+    Barrel re-export layer (re-exports core, nodejs).
+    Contains legacy NodeRuntime facade class.
 ```
 
-## NodeRuntime / PythonRuntime
+## Kernel (createKernel)
+
+`packages/secure-exec-core/src/kernel/kernel.ts`
+
+Primary API. Creates a kernel with shared VFS, FD table, process table, device layer, pipes, PTY, and command registry.
+
+- `kernel.mount(driver)` — register a RuntimeDriver and its commands
+- `kernel.exec(command)` — high-level execute-and-collect (spawn via shell, capture stdout/stderr)
+- `kernel.spawn(command, args, options)` — low-level process spawn with PID allocation and FD table setup
+- `kernel.openShell(options)` — open an interactive PTY shell
+- `kernel.dispose()` — terminate all processes and release resources
 
-`packages/secure-exec-core/src/runtime.ts`, `packages/secure-exec-core/src/python-runtime.ts`
+## NodeRuntime (legacy facade)
 
-Public APIs. Thin facades that delegate orchestration to execution drivers.
+`packages/secure-exec/src/runtime.ts`
+
+Legacy facade for direct code execution. Delegates to execution drivers.
 
 - `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
+- `NodeRuntime.exec(code)` — execute as script, get exit code/error contract
 - `dispose()` / `terminate()`
 - Requires both:
   - `systemDriver` for runtime capabilities/config
@@ -58,7 +81,7 @@ Public APIs. Thin facades that delegate orchestration to execution drivers.
 
 `packages/secure-exec-core/src/types.ts`
 
-Config object that bundles what the isolate can access. Deny-by-default.
+Config object that bundles what the isolate can access. Deny-by-default. Used by the legacy NodeRuntime facade.
 
 - `filesystem` — VFS adapter
 - `network` — fetch, DNS, HTTP
@@ -91,6 +114,16 @@ Factory that builds a Node-backed execution driver factory.
 - Constructs `NodeExecutionDriver` instances
 - Owns optional Node-specific isolate creation hook
 
+### createNodeRuntime()
+
+`packages/secure-exec-nodejs/src/kernel-runtime.ts`
+
+Factory that creates a kernel-compatible Node RuntimeDriver for use with `kernel.mount()`.
+
+- Returns a `KernelRuntimeDriver` with commands like `node`, `npx`, `npm`
+- Manages V8 session lifecycle for kernel-spawned processes
+- Bridges kernel VFS/FD table into Node execution context
+
 ### createBrowserDriver()
 
 `packages/secure-exec-browser/src/driver.ts`
@@ -120,6 +153,25 @@ Factory that builds a Python-backed execution driver factory.
 - Constructs `PyodideRuntimeDriver` instances
 - Owns Pyodide worker bootstrap and execution-driver creation options
 
+### createPythonRuntime()
+
+`packages/secure-exec-python/src/kernel-runtime.ts`
+
+Factory that creates a kernel-compatible Python RuntimeDriver for use with `kernel.mount()`.
+
+- Returns a `KernelRuntimeDriver` with `python` command
+- Manages Pyodide worker lifecycle for kernel-spawned processes
+
+### createWasmVmRuntime()
+
+`packages/secure-exec-wasmvm/src/runtime.ts`
+
+Factory that creates a kernel-compatible WasmVM RuntimeDriver for use with `kernel.mount()`.
+
+- Returns a `KernelRuntimeDriver` with POSIX commands (`sh`, `ls`, `cat`, `grep`, etc.)
+- Loads WASM binaries from `native/wasmvm/target/`
+- Manages WASI polyfill and kernel worker threads
+
 ## @secure-exec/v8 (V8 Runtime)
 
 `packages/secure-exec-v8/`
@@ -219,7 +271,3 @@ Wraps each adapter with allow/deny checks before calls reach the host.
 
 - `wrapFileSystem()`, `wrapNetworkAdapter()`, `wrapCommandExecutor()`
 - Missing adapters get deny-all stubs
-
----
-
-> **Kernel packages** (`packages/kernel/`, `packages/runtime/`, `packages/os/`) are experimental and not part of the public API. See `native/wasmvm/CLAUDE.md` for kernel and WasmVM architecture details.

scripts/ralph/prd.json

@@ -265,7 +265,7 @@
         "Typecheck passes"
       ],
       "priority": 17,
-      "passes": false,
+      "passes": true,
       "notes": "Phase 7 step 1. Only delete after all merges are complete."
     },
     {
@@ -283,7 +283,7 @@
         "Typecheck passes"
       ],
       "priority": 18,
-      "passes": false,
+      "passes": true,
       "notes": "Phase 7 step 2. Final verification of the full consolidation."
     },
     {