feat(cpython): real CPython 3.14 as python3 in a WebAssembly sandbox

.github/dependabot.yml

@@ -51,6 +51,13 @@ updates:
       - dependency-name: "monty"
       - dependency-name: "monty-types"
 
+      # wasmtime is pinned exactly (=48.0.5): the `cpython` feature embeds a
+      # module precompiled by build.rs, and a precompiled module loads only
+      # into the same wasmtime version. 49.x also needs a newer rustc than
+      # rust-toolchain.toml pins. Bump deliberately together with the
+      # toolchain; see knowledge/runtimes/cpython-wasm.md.
+      - dependency-name: "wasmtime"
+
       # idna_adapter is deliberately held at 1.0.0. It is not a normal
       # dependency: the crate exists so the top-level lockfile can choose
       # `idna`'s Unicode back end, and 1.0.x is the "no back end" stream that

.github/workflows/ci.yml

@@ -220,7 +220,9 @@ jobs:
       - name: Install cargo-vet
         uses: taiki-e/install-action@83ac0ad63c0167e6f06796fab0fce28db1bf3db0 # v2
         with:
-          tool: cargo-vet
+          # 0.10.2+ parses trusted-publisher entries in imports.lock (wasmtime
+          # crates publish via GitHub trusted publishing); 0.10.0 rejects them.
+          tool: cargo-vet@0.10.2
 
       - name: Supply chain audit (cargo-vet)
         run: cargo vet --locked
@@ -300,6 +302,12 @@ jobs:
       - name: Run doc tests
         run: cargo test --workspace --doc --features http_client,ssh,sqlite
 
+      # CPython (wasm) python3: unit, integration, capability (diffed against
+      # the runner's python3), security and load tests. Feature-gated, so the
+      # main test step above does not build it into bashkit.
+      - name: Run CPython tests
+        run: cargo test -p bashkit --features cpython --lib --test integration -- cpython
+
       - name: Run realfs tests
         run: cargo test --features realfs -p bashkit --test realfs_tests -p bashkit-cli
 
@@ -422,6 +430,7 @@ jobs:
           cargo run --example live_mounts
           cargo run --example git_workflow --features git
           cargo run --example python_external_functions --features python
+          cargo run --example cpython_scripts --features cpython
           cargo run --example typescript_external_functions --features typescript
           cargo run --example realfs_readonly --features realfs
           cargo run --example realfs_readwrite --features realfs
@@ -552,7 +561,9 @@ jobs:
 
       - name: Verify fuzz targets compile
         working-directory: crates/bashkit
-        run: cargo +nightly fuzz build
+        run: |
+          cargo +nightly fuzz build
+          cargo +nightly fuzz build --features cpython cpython_fuzz
 
   # Gate job for branch protection — name must stay "Check"
   check:

.github/workflows/fuzz.yml

@@ -26,7 +26,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        target: [parser_fuzz, lexer_fuzz, analyze_fuzz, arithmetic_fuzz, glob_fuzz]
+        target: [parser_fuzz, lexer_fuzz, analyze_fuzz, arithmetic_fuzz, glob_fuzz, cpython_fuzz]
 
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -60,7 +60,9 @@ jobs:
             echo "::error::duration must be a positive integer with no leading zeros, got: $DURATION_INPUT"
             exit 1
           fi
-          cargo +nightly fuzz run ${{ matrix.target }} -- \
+          features=()
+          if [ "${{ matrix.target }}" = cpython_fuzz ]; then features=(--features cpython); fi
+          cargo +nightly fuzz run "${features[@]}" ${{ matrix.target }} -- \
             -max_total_time="$DURATION_INPUT" \
             -print_final_stats=1
 

.github/workflows/publish.yml

@@ -13,10 +13,51 @@ env:
   CARGO_TERM_COLOR: always
 
 jobs:
+  # Publish bashkit-cpython-wasm (optional dependency of bashkit's `cpython`
+  # feature; must exist on crates.io before bashkit can be verified)
+  publish-bashkit-cpython-wasm:
+    name: Publish bashkit-cpython-wasm
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Verify publish source is on main
+        run: |
+          git fetch --no-tags origin main:refs/remotes/origin/main
+          SOURCE_SHA=$(git rev-parse HEAD)
+          if ! git merge-base --is-ancestor "$SOURCE_SHA" origin/main; then
+            echo "Error: publish source $SOURCE_SHA is not reachable from origin/main"
+            exit 1
+          fi
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@e081816240890017053eacbb1bdf337761dc5582 # 1.95.0
+
+      - name: Verify bashkit-cpython-wasm package without credentials
+        run: |
+          cargo publish --dry-run -p bashkit-cpython-wasm
+          # crates.io rejects crates over 10 MiB; the embedded snapshot and
+          # stdlib keep this one close to that limit.
+          size=$(stat -c %s target/package/bashkit-cpython-wasm-*.crate)
+          echo "crate size: $size bytes"
+          if [ "$size" -ge 10485760 ]; then
+            echo "Error: bashkit-cpython-wasm crate exceeds the crates.io 10 MiB limit"
+            exit 1
+          fi
+
+      - name: Publish bashkit-cpython-wasm to crates.io
+        run: cargo publish --no-verify -p bashkit-cpython-wasm
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+
   # Publish bashkit (core library) to crates.io
   publish-bashkit:
     name: Publish bashkit
     runs-on: ubuntu-latest
+    needs: publish-bashkit-cpython-wasm
     environment: release
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -59,6 +100,9 @@ jobs:
           fi
           echo "Version verified: $TAG_VERSION"
 
+      - name: Wait for crates.io index update
+        run: sleep 30
+
       - name: Verify bashkit package without credentials
         run: cargo publish --dry-run -p bashkit
 
@@ -123,7 +167,7 @@ jobs:
   verify-publish:
     name: Verify published versions
     runs-on: ubuntu-latest
-    needs: [publish-bashkit, publish-bashkit-cli, publish-bashkit-scripted-tool]
+    needs: [publish-bashkit-cpython-wasm, publish-bashkit, publish-bashkit-cli, publish-bashkit-scripted-tool]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -136,4 +180,4 @@ jobs:
         run: |
           EXPECTED=$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)".*/\1/')
           echo "Expected version: $EXPECTED"
-          python3 scripts/verify_crates_publish.py --expected "$EXPECTED" bashkit bashkit-cli bashkit-scripted-tool
+          python3 scripts/verify_crates_publish.py --expected "$EXPECTED" bashkit-cpython-wasm bashkit bashkit-cli bashkit-scripted-tool

AGENTS.md

@@ -40,6 +40,7 @@ Fix root cause. Unsure: read more code; if stuck, ask w/ short options. Unrecogn
 | integrations/script-analysis | Static pre-execution script introspection for permission gating |
 | integrations/git-support | Sandboxed git operations on VFS |
 | runtimes/python-builtin | Embedded Python via Monty, security, resource limits |
+| runtimes/cpython-wasm | Real CPython 3.14 on WASI (Wizer snapshot, Pulley AOT), WASI-on-VFS host, limits |
 | operations/eval | LLM eval study on the mira framework, dataset format, scoring |
 | operations/maintenance | Pre-release maintenance requirements |
 | runtimes/python-package | Python package, PyPI wheels, platform matrix |