Perf/sandbox lifecycle

.gitattributes

@@ -0,0 +1,2 @@
+*.patch -whitespace
+compat/e2b/spec/** -whitespace

.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
     name: Format
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Init submodules
         run: git -c http.extraheader= submodule update --init --recursive
       - uses: dtolnay/rust-toolchain@stable
@@ -30,7 +30,7 @@ jobs:
     name: Clippy
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Init submodules
         run: git -c http.extraheader= submodule update --init --recursive
       - uses: dtolnay/rust-toolchain@stable
@@ -54,7 +54,7 @@ jobs:
     name: Test
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Init submodules
         run: git -c http.extraheader= submodule update --init --recursive
       - uses: dtolnay/rust-toolchain@stable
@@ -71,10 +71,81 @@ jobs:
           workspaces: src
       - run: cd src && cargo test --workspace --lib
 
+  # ── Pinned E2B protocol and SDK surface drift gate ────────────
+  e2b-contract:
+    name: E2B Contract
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Install protoc
+        run: sudo apt-get update && sudo apt-get install -y protobuf-compiler
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: src
+      - name: Verify pinned contracts and SDK exports
+        run: cd src && cargo run -p a3s-box-compat --bin a3s-box-e2b-contract -- verify
+
+  # ── Pinned official E2B client wire compatibility gate ────────
+  e2b-official-clients:
+    name: E2B Official Clients
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '20'
+      - uses: astral-sh/setup-uv@v8.3.2
+        with:
+          version: '0.11.8'
+          enable-cache: false
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Build Rust lifecycle fixture server
+        run: cd src && cargo build -p a3s-box-compat --bin a3s-box-e2b-fixture-server
+      - name: Test production client harness
+        run: python3 compat/e2b/fixtures/official-clients/test_run_production.py -v
+      - name: Verify official client lifecycle requests
+        run: >-
+          python3 compat/e2b/fixtures/official-clients/run_fixtures.py verify
+          --rust-server-bin src/target/debug/a3s-box-e2b-fixture-server
+
+  # ── Native Python and TypeScript SDK package gate ─────────────
+  sdk-packages:
+    name: SDK Packages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: sdk/typescript/package-lock.json
+      - name: Build and test Python package
+        run: |
+          python -m pip install build
+          python -m build sdk/python
+          python -m venv /tmp/a3s-box-python-sdk
+          /tmp/a3s-box-python-sdk/bin/pip install sdk/python/dist/*.whl
+          /tmp/a3s-box-python-sdk/bin/python -m unittest discover -s sdk/python/tests
+      - name: Build and test TypeScript package
+        working-directory: sdk/typescript
+        run: |
+          npm ci
+          npm run build
+          npm test
+          npm pack --dry-run
+
   # ── Build check (compile only, no artifacts) ────────────────────
   build-check:
     name: Build Check (${{ matrix.target }})
-    needs: [fmt, clippy, test]
+    needs: [fmt, clippy, test, e2b-contract, e2b-official-clients, sdk-packages]
     strategy:
       matrix:
         include:
@@ -86,7 +157,7 @@ jobs:
             os: macos-14
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Init submodules
         run: git -c http.extraheader= submodule update --init --recursive
 
@@ -115,15 +186,16 @@ jobs:
           cargo check --release -p a3s-box-cli -p a3s-box-shim
           if [ "${{ runner.os }}" = "Linux" ]; then
             cargo check --release -p a3s-box-cri
+            cargo check --release -p a3s-box-compat --bin a3s-box-e2b
           fi
 
   # ── Windows native WHPX build check ────────────────────────────
   build-windows:
     name: Build Windows WHPX
-    needs: [fmt, clippy, test]
+    needs: [fmt, clippy, test, e2b-contract, e2b-official-clients, sdk-packages]
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Init submodules
         run: git -c http.extraheader= submodule update --init --recursive
       - uses: dtolnay/rust-toolchain@stable
@@ -139,7 +211,7 @@ jobs:
           cd src
           cargo build --release -p a3s-box-cli -p a3s-box-shim --target x86_64-pc-windows-msvc
       - name: Upload artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: windows-whpx
           path: |
@@ -162,7 +234,7 @@ jobs:
   # Until both are done this job is SKIPPED (inert) and never blocks a PR.
   integration-kvm:
     name: Integration (real microVM, KVM)
-    needs: [fmt, clippy, test]
+    needs: [fmt, clippy, test, e2b-contract, e2b-official-clients, sdk-packages]
     if: vars.KVM_CI == 'true'
     runs-on: [self-hosted, linux, kvm]
     timeout-minutes: 75
@@ -173,7 +245,7 @@ jobs:
     env:
       A3S_REGISTRY_MIRRORS: ${{ vars.KVM_CI_REGISTRY_MIRRORS || 'docker.io=docker.m.daocloud.io' }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Init submodules
         run: git -c http.extraheader= submodule update --init --recursive
       # The self-hosted runner already has a working rustup/cargo. Using
@@ -210,6 +282,23 @@ jobs:
           unset A3S_DEPS_STUB
           cd src
           cargo test --release -p a3s-box-cli --test core_smoke -- --ignored --nocapture --test-threads=1
+      # Keep the cached foreground no-op inside a bounded production envelope.
+      # Docker is intentionally unavailable on this runner; the original
+      # macOS/HVF Docker ratio remains a separate hardware-specific comparison.
+      - name: Foreground latency — cached no-op p50 regression gate
+        env:
+          A3S_BOX: ${{ github.workspace }}/src/target/release/a3s-box
+          IMAGE: ${{ vars.KVM_CI_AGENT_IMAGE || 'docker.m.daocloud.io/library/alpine:latest' }}
+          FOREGROUND_RUNS: "10"
+          FOREGROUND_WARMUPS: "1"
+          FOREGROUND_DOCKER: "0"
+          # Default includes headroom for normal runner noise; dedicated
+          # runners can tighten it with the repository variable.
+          FOREGROUND_MAX_P50_MS: ${{ vars.KVM_CI_FOREGROUND_MAX_P50_MS || '3200' }}
+        run: |
+          unset A3S_DEPS_STUB
+          chmod +x bench/bench.sh
+          bench/bench.sh foreground
       - name: CRI crictl smoke — full pod/container lifecycle
         env:
           A3S_BOX_CRI_SMOKE: "1"

.github/workflows/e2b-runtime-image.yml

@@ -0,0 +1,63 @@
+name: E2B Runtime Image
+
+on:
+  push:
+    branches:
+      - main
+      - "feat/e2b-*"
+    paths:
+      - "deploy/e2b/**"
+      - ".github/workflows/e2b-runtime-image.yml"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  packages: write
+
+concurrency:
+  group: e2b-runtime-image-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Test envd initialization
+        run: python3 -m unittest discover -s deploy/e2b -p 'test_*.py'
+
+      - uses: docker/setup-qemu-action@v3
+
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Generate image metadata
+        id: metadata
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/a3s-lab/box-e2b-runtime
+          tags: |
+            type=sha,format=long
+            type=raw,value=edge,enable={{is_default_branch}}
+
+      - name: Build and push the runtime image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: deploy/e2b/Dockerfile
+          platforms: ${{ github.ref == 'refs/heads/main' && 'linux/amd64,linux/arm64' || 'linux/amd64' }}
+          push: true
+          tags: ${{ steps.metadata.outputs.tags }}
+          labels: ${{ steps.metadata.outputs.labels }}
+          cache-from: type=gha,scope=e2b-runtime
+          cache-to: type=gha,mode=max,scope=e2b-runtime
+          provenance: mode=max
+          sbom: true

.github/workflows/publish-libkrun-sys.yml

@@ -20,7 +20,7 @@ jobs:
     name: Build Windows krun.dll
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           submodules: recursive
 
@@ -61,47 +61,47 @@ jobs:
 
           # Create README
           @"
-# a3s-libkrun-sys Windows Build
+          # a3s-libkrun-sys Windows Build
 
-Version: $VERSION
-Platform: Windows x86_64 (WHPX)
-Built: $(Get-Date -Format "yyyy-MM-dd HH:mm:ss UTC")
+          Version: $VERSION
+          Platform: Windows x86_64 (WHPX)
+          Built: $(Get-Date -Format "yyyy-MM-dd HH:mm:ss UTC")
 
-## Contents
+          ## Contents
 
-- lib/krun.dll - libkrun Windows WHPX backend
+          - lib/krun.dll - libkrun Windows WHPX backend
 
-## Usage
+          ## Usage
 
-Add to your Cargo.toml:
+          Add to your Cargo.toml:
 
-``````toml
-[dependencies]
-a3s-libkrun-sys = "$VERSION"
-``````
+          ``````toml
+          [dependencies]
+          a3s-libkrun-sys = "$VERSION"
+          ``````
 
-The krun.dll must be in your PATH or in the same directory as your executable.
+          The krun.dll must be in your PATH or in the same directory as your executable.
 
-## Features
+          ## Features
 
-- Windows Hypervisor Platform (WHPX) backend
-- virtiofs passthrough filesystem
-- virtio-net TCP backend
-- virtio-blk block device
-- virtio-console
-- TSI (Transparent Socket Impersonation) for vsock
+          - Windows Hypervisor Platform (WHPX) backend
+          - virtiofs passthrough filesystem
+          - virtio-net TCP backend
+          - virtio-blk block device
+          - virtio-console
+          - TSI (Transparent Socket Impersonation) for vsock
 
-## Requirements
+          ## Requirements
 
-- Windows 10/11 with Hyper-V Platform enabled
-- Run: ``Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform``
-"@ | Out-File -FilePath $DIR\README.md -Encoding UTF8
+          - Windows 10/11 with Hyper-V Platform enabled
+          - Run: ``Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform``
+          "@ | Out-File -FilePath $DIR\README.md -Encoding UTF8
 
           # Create zip
           Compress-Archive -Path $DIR -DestinationPath "$DIR.zip"
           echo "ASSET=$DIR.zip" >> $env:GITHUB_ENV
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v6
         with:
           name: windows-dll
           path: ${{ env.ASSET }}
@@ -112,7 +112,7 @@ The krun.dll must be in your PATH or in the same directory as your executable.
     needs: build-windows-dll
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           submodules: recursive
 
@@ -138,9 +138,9 @@ The krun.dll must be in your PATH or in the same directory as your executable.
     needs: [build-windows-dll, publish-crate]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v7
         with:
           name: windows-dll
           path: artifacts
@@ -181,4 +181,3 @@ The krun.dll must be in your PATH or in the same directory as your executable.
             artifacts/*.zip
           draft: false
           prerelease: false
-