feat: WasmVM dynamic modules - POSIX-compliant WASM runtime (squashed ralph/wasmvm-dynamic-modules)

Full WasmVM runtime with POSIX-compliant process model, VFS, PTY, signals,
pipes, FD table, and shell integration. Includes 98 user stories covering:

- WasmVM Rust workspace migration and monorepo integration
- Kernel process table, FD table, and VFS implementation
- WASI host imports (host_process, host_user, host_net)
- C toolchain with wasi-libc patches for process spawning
- Interactive shell (brush-shell) with PTY support
- Dynamic module loading and permission tiers
- Network proxy and HTTP client via host_net
- Codex CLI stub binaries (to be replaced with real fork)
- C parity test suite for syscall coverage
- Documentation and compatibility tracking

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

Author: NathanFlurry

.github/workflows/ci.yml

@@ -37,6 +37,34 @@ jobs:
       - name: Build WASM binary
         run: cd wasmvm && make wasm
 
+      # --- C toolchain (wasi-sdk + patched sysroot + C test fixtures) ---
+      - name: Cache wasi-sdk
+        id: cache-wasi-sdk
+        uses: actions/cache@v4
+        with:
+          path: wasmvm/c/vendor/wasi-sdk
+          key: wasi-sdk-25-${{ runner.os }}-${{ runner.arch }}
+
+      - name: Download wasi-sdk
+        if: steps.cache-wasi-sdk.outputs.cache-hit != 'true'
+        run: make -C wasmvm/c wasi-sdk
+
+      - name: Cache patched wasi-libc sysroot
+        id: cache-sysroot
+        uses: actions/cache@v4
+        with:
+          path: |
+            wasmvm/c/sysroot
+            wasmvm/c/vendor/wasi-libc
+          key: wasi-libc-sysroot-${{ runner.os }}-${{ hashFiles('wasmvm/patches/wasi-libc/*.patch', 'wasmvm/scripts/patch-wasi-libc.sh') }}
+
+      - name: Build patched wasi-libc sysroot
+        if: steps.cache-sysroot.outputs.cache-hit != 'true'
+        run: make -C wasmvm/c sysroot
+
+      - name: Build C test fixtures (WASM + native)
+        run: make -C wasmvm/c programs native
+
       # --- Node.js / TypeScript ---
       - name: Set up pnpm
         uses: pnpm/action-setup@v4

CLAUDE.md

@@ -33,17 +33,34 @@
 - 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
 
+## Tool Integration Policy
+
+- NEVER implement a from-scratch reimplementation of a tool when the PRD specifies using an existing upstream project (e.g., codex, curl, git, make)
+- always fork, vendor, or depend on the real upstream source — do not build a "stub" or "demo" binary that fakes the tool's behavior
+- if the upstream cannot compile or link for the target, document the specific blockers and leave the story as failing — do not mark it passing with a placeholder
+- the PRD and story notes define which upstream project to use; follow them exactly unless explicitly told otherwise
+
 ## WASM Binary
 
+- the goal for WasmVM is full POSIX compliance 1:1 — every command, syscall, and shell behavior should match a real Linux system exactly
 - WasmVM and Python are experimental surfaces in this repo
 - all docs for WasmVM, Python, or other experimental runtime features must live under the `Experimental` section of the docs navigation, not the main getting-started/reference sections
-- the WasmVM runtime requires a WASM binary at `wasmvm/target/wasm32-wasip1/release/multicall.wasm`
-- build it locally: `cd wasmvm && make wasm` (requires Rust nightly + wasm32-wasip1 target + rust-src component + wasm-opt/binaryen)
+- the WasmVM runtime requires standalone WASM binaries in `wasmvm/target/wasm32-wasip1/release/commands/`
+- build them locally: `cd wasmvm && make wasm` (requires Rust nightly + wasm32-wasip1 target + rust-src component + wasm-opt/binaryen)
 - the Rust toolchain is pinned in `wasmvm/rust-toolchain.toml` — rustup will auto-install it
-- CI builds the binary before tests; a CI-only guard test in `packages/runtime/wasmvm/test/driver.test.ts` fails if it's missing
-- tests gated behind `skipIf(!hasWasmBinary)` or `skipUnlessWasmBuilt()` will skip locally if the binary isn't built
+- CI builds the binaries before tests; a CI-only guard test in `packages/runtime/wasmvm/test/driver.test.ts` fails if they're missing
+- tests gated behind `skipIf(!hasWasmBinaries)` or `skipUnlessWasmBuilt()` will skip locally if binaries aren't built
 - see `wasmvm/CLAUDE.md` for full build details and architecture
 
+## WasmVM Syscall Coverage
+
+- every function in the `host_process` and `host_user` import modules (declared in `wasmvm/crates/wasi-ext/src/lib.rs`) must have at least one C parity test exercising it through libc
+- when adding a new host import, add a matching test case to `wasmvm/c/programs/syscall_coverage.c` and its parity test in `packages/runtime/wasmvm/test/c-parity.test.ts`
+- the canonical source of truth for import signatures is `wasmvm/crates/wasi-ext/src/lib.rs` — C patches and JS host implementations must match exactly
+- C patches in `wasmvm/patches/wasi-libc/` must be kept in sync with wasi-ext — ABI drift between C, Rust, and JS is a P0 bug
+- permission tier enforcement must cover ALL write/spawn/kill/pipe/dup operations — audit `packages/runtime/wasmvm/src/kernel-worker.ts` when adding new syscalls
+- `PATCHED_PROGRAMS` in `wasmvm/c/Makefile` must include all programs that use `host_process` or `host_user` imports (programs linking the patched sysroot)
+
 ## Terminology
 
 - use `docs-internal/glossary.md` for canonical definitions of isolate, runtime, bridge, and driver
@@ -124,6 +141,8 @@ Follow the style in `packages/secure-exec/src/index.ts`.
   - `docs/system-drivers/browser.mdx` — update when createBrowserDriver options change
   - `docs/nodejs-compatibility.mdx` — update when bridge, polyfill, or stub implementations change; keep the Tested Packages section current when adding or removing project-matrix fixtures
   - `docs/cloudflare-workers-comparison.mdx` — update when secure-exec capabilities change; bump "Last updated" date
+  - `docs/posix-compatibility.md` — update when kernel, WasmVM, Node bridge, or Python bridge behavior changes for any POSIX-relevant feature (signals, pipes, FDs, process model, TTY, VFS)
+  - `docs/wasmvm/supported-commands.md` — update when adding, removing, or changing status of WasmVM commands; keep summary counts current
 
 ## Backlog Tracking
 

docs-internal/review-notes.md

@@ -181,14 +181,14 @@ expect(stdout).not.toContain('root:x:0:0');
 
 ### Tests Gated Behind skipIf (May Not Run in CI)
 
-4 WasmVM test suites require `multicall.wasm` binary (external Rust crate, not in repo):
-- `describe.skipIf(!hasWasmBinary)('real execution')` — echo, cat, false
-- `describe.skipIf(!hasWasmBinary)('stdin streaming')` — cat with writeStdin
-- `describe.skipIf(!hasWasmBinary)('proc_spawn routing')` — echo through kernel
+4 WasmVM test suites require standalone WASM binaries (built from Rust crates via `make wasm`):
+- `describe.skipIf(!hasWasmBinaries)('real execution')` — echo, cat, false
+- `describe.skipIf(!hasWasmBinaries)('stdin streaming')` — cat with writeStdin
+- `describe.skipIf(!hasWasmBinaries)('proc_spawn routing')` — echo through kernel
 
 All E2E tests with real npm skip if npm registry unreachable.
 
-**Risk:** If CI doesn't build the WASM binary or lacks network, these tests silently skip and the suite still passes green.
+**Risk:** If CI doesn't build WASM binaries or lacks network, these tests silently skip and the suite still passes green. (Mitigated: CI-only guard test asserts binaries exist.)
 
 ---
 
@@ -335,7 +335,7 @@ What IS abstracted:
 
 ### P1 — Fix Before Production
 3. **Security boundary tests**: Add symlink escape, path traversal, host binary access, and resource limit enforcement tests.
-4. **WASM binary in CI**: Ensure CI builds multicall.wasm so gated tests actually run. Silent skips create false confidence.
+4. **WASM binaries in CI**: (RESOLVED) CI builds standalone WASM binaries via `make wasm`. Guard test fails if binaries are missing.
 5. **Permission wrapper tests**: The permission system exists but has zero test coverage. Add deny-scenario tests.
 6. **Replace negative security assertions**: "output doesn't contain X" tests should be replaced with positive assertions about error behavior.
 

docs-internal/spec-hardening.md

@@ -204,12 +204,12 @@ Addresses bugs, test quality gaps, missing coverage, and documentation debt iden
 
 ### 14. WASM Binary CI Availability
 
-**Problem:** WasmVM real execution tests are gated behind `skipIf(!hasWasmBinary)`. If CI doesn't build the Rust crate, all real execution tests silently skip. The test suite reports green despite not running critical tests.
+**Problem:** WasmVM real execution tests are gated behind `skipIf(!hasWasmBinaries)`. If CI doesn't build the Rust crates, all real execution tests silently skip. The test suite reports green despite not running critical tests.
 
-**Acceptance criteria:**
-- CI pipeline builds `wasmvm/target/wasm32-wasip1/release/multicall.wasm` before test runs
-- OR: Add a CI-only test that asserts `hasWasmBinary === true` so CI fails if binary is missing
-- Document in CLAUDE.md how to build the WASM binary locally
+**Acceptance criteria:** (RESOLVED)
+- CI pipeline runs `make wasm` to build standalone binaries to `wasmvm/target/wasm32-wasip1/release/commands/`
+- CI-only test asserts `hasWasmBinaries === true` so CI fails if binaries are missing
+- CLAUDE.md documents how to build locally
 
 ### 15. Error String Matching → Structured Errors (WasmVM)