chore(rivetkit): build wasm package in publish workflow

Author: NathanFlurry

.agent/specs/rivetkit-core-wasm-support.md

@@ -9,14 +9,26 @@ Support a WebAssembly build of RivetKit core while keeping the existing native N
 
 This proposal is intentionally gate-oriented: implementation should not start until the parity, rollout, and failure-mode criteria below are accepted.
 
+## Implemented Invariants
+
+- Remote SQL is an envoy protocol v4-only capability. Older protocol targets reject remote SQL request and response serialization with `ProtocolCompatibilityError { feature: RemoteSqliteExecution, required_version: 4, ... }`, and runtime callers map unsupported remote SQL to `sqlite.remote_unavailable` instead of a BARE decode failure.
+- Wasm uses remote SQLite only. The valid SQLite driver cells are native/local/all encodings, native/remote/all encodings, and wasm/remote/all encodings; wasm/local is invalid and covered by a targeted unavailable assertion.
+- Shared SQLite bind, value, result, and route types live in `rivetkit-sqlite-types`. Native and remote execution both route through the shared SQLite execution layer so statement classification, writer stickiness, migrations, `execute_write`, and manual transactions stay aligned.
+- `pegboard-envoy` creates at most one remote SQL executor per active `(actor_id, sqlite_generation)`. The executor is created lazily on the first accepted SQL request, reused for that generation, and removed when the actor closes or the connection shuts down.
+- Remote SQL work runs outside the pegboard-envoy WebSocket read loop in bounded workers. Accepted SQL is tracked per `(actor_id, sqlite_generation)`; actor stop rejects new SQL after stopping begins and waits for already accepted SQL before closing storage.
+- Sent remote SQL requests fail with `sqlite.remote_indeterminate_result` if the WebSocket disconnects before the response arrives. Only unsent requests may be sent after reconnect.
+- `rivet-envoy-client` owns native versus wasm WebSocket transport selection through mutually exclusive `native-transport` and `wasm-transport` features. `rivetkit-core` selects transport by enabling `native-runtime` or `wasm-runtime`.
+- The wasm binding strategy is direct `wasm-bindgen` in `@rivetkit/rivetkit-wasm`. Native NAPI and wasm bindings both adapt into the shared TypeScript `CoreRuntime` interface; raw binding imports stay inside approved runtime adapter files.
+- `scripts/cargo/check-rivetkit-core-wasm.sh` is the canonical wasm dependency gate for `rivetkit-core`.
+
 ## Current State
 
 - `rivetkit-core` owns `ActorContext::sql()` and currently routes `exec`, `query`, `run`, `execute`, and `execute_write` through `SqliteDb`.
-- With the `sqlite` feature enabled, `SqliteDb` opens `rivetkit-sqlite::NativeDatabaseHandle`, which uses native `libsqlite3-sys` plus a custom VFS.
-- With the `sqlite` feature disabled, `SqliteDb` keeps the public API but returns `sqlite.unavailable` for SQL execution.
-- The existing envoy SQLite protocol is page/storage oriented: `get_pages`, `get_page_range`, `commit`, staged commit, and preload hints.
-- `pegboard-envoy` already validates SQLite requests and owns an `Arc<sqlite_storage::SqliteEngine>`, but it does not execute SQL text today.
-- The first wasm compile probe fails before core code due to native Tokio networking: `cargo check -p rivetkit-core --target wasm32-unknown-unknown --no-default-features` hits `mio`'s wasm unsupported error. The dependency path is primarily `rivetkit-core -> rivet-envoy-client -> tokio-tungstenite -> tokio/mio`, plus `rivet-pools`, `reqwest`, and `nix`.
+- With `sqlite-local`, `SqliteDb` opens `rivetkit-sqlite::NativeDatabaseHandle`, which uses native `libsqlite3-sys` plus a custom VFS.
+- With `sqlite-remote`, `SqliteDb` sends SQL through envoy remote execution. With no usable backend, the public API returns explicit structured unavailable errors.
+- The envoy SQLite protocol now includes both the page/storage path and v4 SQL execution requests for `exec`, `execute`, and `execute_write`.
+- `pegboard-envoy` validates remote SQL namespace, actor, generation, request size, and response size before executing through the shared SQLite execution layer.
+- The canonical wasm compile and dependency check is `scripts/cargo/check-rivetkit-core-wasm.sh`.
 
 ## Phase 1: Remote SQLite SQL Execution
 
@@ -621,7 +633,7 @@ Run `scripts/cargo/check-rivetkit-core-wasm.sh` before claiming wasm dependency
 - Decision: direct wasm-bindgen on `wasm32-unknown-unknown` is the wasm binding path for Supabase and Cloudflare.
 - Decision: NAPI-RS wasm is not viable for the mainline edge-host binding because the spike showed async/callback surfaces fail in workerd when Rust tries to spawn a thread.
 - Open: exact numeric defaults for SQL text, bind bytes, row count, cell bytes, response bytes, and execution timeout.
-- Open: whether remote writes use durable request IDs and server-side deduplication or fail with an indeterminate-result error on lost responses.
+- Decision: sent remote SQL requests fail with `sqlite.remote_indeterminate_result` on lost responses; durable request ID deduplication is a future enhancement.
 - Decision: remote SQL calls already accepted before actor stopping may finish, but new calls after stopping begins are rejected.
 - Open: whether workflow/agent-os are in scope for the first wasm package or deferred as explicit non-goals.
 - Decision: Node wasm and WASI are follow-up targets. They do not replace Supabase and Cloudflare acceptance.
@@ -646,4 +658,4 @@ Run `scripts/cargo/check-rivetkit-core-wasm.sh` before claiming wasm dependency
 - Supabase Edge Functions WebAssembly guide: https://supabase.com/docs/guides/functions/wasm
 - Cloudflare Workers WebAssembly API docs: https://developers.cloudflare.com/workers/runtime-apis/webassembly/
 - reqwest crate docs for WebAssembly support: https://docs.rs/reqwest/latest/reqwest/
-- Local compile probe: `cargo check -p rivetkit-core --target wasm32-unknown-unknown --no-default-features` currently fails in `mio` because native Tokio networking is still included.
+- Local compile gate: `scripts/cargo/check-rivetkit-core-wasm.sh`.

.github/workflows/publish.yaml

@@ -79,7 +79,7 @@ jobs:
           fi
 
   # ---------------------------------------------------------------------------
-  # build — matrix of 10 native/engine artifacts (11 on release for Windows)
+  # build — matrix of native/engine artifacts
   # ---------------------------------------------------------------------------
   build:
     needs: [context]
@@ -232,6 +232,45 @@ jobs:
           path: artifacts/${{ matrix.artifact }}
           if-no-files-found: error
 
+  # ---------------------------------------------------------------------------
+  # build-wasm — wasm package artifact built in parallel with native artifacts
+  # ---------------------------------------------------------------------------
+  build-wasm:
+    needs: [context]
+    name: "Build rivetkit-wasm"
+    if: needs.context.outputs.is_fork != 'true'
+    runs-on: depot-ubuntu-24.04-8
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          lfs: ${{ needs.context.outputs.trigger == 'release' }}
+      - run: corepack enable
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: pnpm
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: stable
+          target: wasm32-unknown-unknown
+          rustflags: ""
+      - uses: Swatinem/rust-cache@v2
+        with:
+          shared-key: "rivetkit-wasm-publish"
+          cache-on-failure: true
+      - name: Install wasm package dependencies
+        run: pnpm install --frozen-lockfile --filter=@rivetkit/rivetkit-wasm
+      - name: Build wasm package
+        run: pnpm --filter=@rivetkit/rivetkit-wasm build
+      - name: Upload wasm package artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: wasm-package
+          path: rivetkit-typescript/packages/rivetkit-wasm/pkg
+          if-no-files-found: error
+
   # ---------------------------------------------------------------------------
   # docker-images — per-arch runtime images pushed to Docker Hub
   # ---------------------------------------------------------------------------
@@ -298,12 +337,13 @@ jobs:
   # publish — npm publish + R2 upload + Docker manifest + release tail
   # ---------------------------------------------------------------------------
   publish:
-    needs: [context, build, docker-images]
+    needs: [context, build, build-wasm, docker-images]
     name: "Publish"
     if: |
       !cancelled() &&
       needs.context.outputs.is_fork != 'true' &&
       needs.build.result == 'success' &&
+      needs.build-wasm.result == 'success' &&
       needs.docker-images.result == 'success'
     runs-on: depot-ubuntu-24.04-8
     permissions:
@@ -343,6 +383,16 @@ jobs:
           path: engine-artifacts
           pattern: engine-*
           merge-multiple: true
+      - name: Download wasm package artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: wasm-package
+          path: rivetkit-typescript/packages/rivetkit-wasm/pkg
+      - name: Validate wasm package artifact
+        run: |
+          test -f rivetkit-typescript/packages/rivetkit-wasm/pkg/rivetkit_wasm.js
+          test -f rivetkit-typescript/packages/rivetkit-wasm/pkg/rivetkit_wasm.d.ts
+          test -f rivetkit-typescript/packages/rivetkit-wasm/pkg/rivetkit_wasm_bg.wasm
 
       - name: Place native binaries in platform packages
         run: |
@@ -397,7 +447,9 @@ jobs:
 
       # ---- build TypeScript packages (turbo dep graph picks up native) ----
       - name: Build TypeScript packages
-        run: pnpm build -F rivetkit -F '@rivetkit/*' -F '!@rivetkit/shared-data' -F '!@rivetkit/engine-frontend' -F '!@rivetkit/mcp-hub' -F '!@rivetkit/rivetkit-napi'
+        env:
+          SKIP_WASM_BUILD: "1"
+        run: pnpm build -F rivetkit -F '@rivetkit/*' -F '!@rivetkit/shared-data' -F '!@rivetkit/engine-frontend' -F '!@rivetkit/mcp-hub' -F '!@rivetkit/rivetkit-napi' -F '!@rivetkit/rivetkit-wasm'
 
       # ---- shared publish (runs for all triggers) ----
       - name: Finalize package versions for publish

docker/build/darwin-arm64.Dockerfile

@@ -35,6 +35,7 @@ COPY . .
 RUN if [ "$BUILD_TARGET" = "engine" ] && [ "$BUILD_FRONTEND" = "true" ]; then \
         export NODE_OPTIONS="--max-old-space-size=8192" && \
         export SKIP_NAPI_BUILD=1 && \
+        export SKIP_WASM_BUILD=1 && \
         pnpm install --ignore-scripts && \
         VITE_APP_API_URL="${VITE_APP_API_URL}" VITE_FEATURE_FLAGS="${VITE_FEATURE_FLAGS}" npx turbo build -F @rivetkit/engine-frontend; \
     fi
@@ -62,7 +63,7 @@ RUN --mount=type=cache,id=cargo-registry-darwin-arm64,target=/usr/local/cargo/re
     fi && \
     mkdir -p /artifacts && \
     if [ "$BUILD_TARGET" = "engine" ]; then \
-        cargo build --bin rivet-engine $CARGO_FLAG --target aarch64-apple-darwin && \
+        cargo build -p rivet-engine --bin rivet-engine $CARGO_FLAG --target aarch64-apple-darwin && \
         cp target/aarch64-apple-darwin/$PROFILE_DIR/rivet-engine /artifacts/rivet-engine-aarch64-apple-darwin; \
     elif [ "$BUILD_TARGET" = "rivetkit-napi" ]; then \
         cd rivetkit-typescript/packages/rivetkit-napi && \

docker/build/darwin-x64.Dockerfile

@@ -35,6 +35,7 @@ COPY . .
 RUN if [ "$BUILD_TARGET" = "engine" ] && [ "$BUILD_FRONTEND" = "true" ]; then \
         export NODE_OPTIONS="--max-old-space-size=8192" && \
         export SKIP_NAPI_BUILD=1 && \
+        export SKIP_WASM_BUILD=1 && \
         pnpm install --ignore-scripts && \
         VITE_APP_API_URL="${VITE_APP_API_URL}" VITE_FEATURE_FLAGS="${VITE_FEATURE_FLAGS}" npx turbo build -F @rivetkit/engine-frontend; \
     fi
@@ -62,7 +63,7 @@ RUN --mount=type=cache,id=cargo-registry-darwin-x64,target=/usr/local/cargo/regi
     fi && \
     mkdir -p /artifacts && \
     if [ "$BUILD_TARGET" = "engine" ]; then \
-        cargo build --bin rivet-engine $CARGO_FLAG --target x86_64-apple-darwin && \
+        cargo build -p rivet-engine --bin rivet-engine $CARGO_FLAG --target x86_64-apple-darwin && \
         cp target/x86_64-apple-darwin/$PROFILE_DIR/rivet-engine /artifacts/rivet-engine-x86_64-apple-darwin; \
     elif [ "$BUILD_TARGET" = "rivetkit-napi" ]; then \
         cd rivetkit-typescript/packages/rivetkit-napi && \

docker/build/linux-arm64-gnu.Dockerfile

@@ -22,6 +22,7 @@ COPY . .
 RUN if [ "$BUILD_TARGET" = "engine" ] && [ "$BUILD_FRONTEND" = "true" ]; then \
         export NODE_OPTIONS="--max-old-space-size=8192" && \
         export SKIP_NAPI_BUILD=1 && \
+        export SKIP_WASM_BUILD=1 && \
         pnpm install --ignore-scripts && \
         VITE_APP_API_URL="${VITE_APP_API_URL}" VITE_FEATURE_FLAGS="${VITE_FEATURE_FLAGS}" npx turbo build -F @rivetkit/engine-frontend; \
     fi
@@ -49,7 +50,7 @@ RUN --mount=type=cache,id=cargo-registry-linux-arm64-gnu,target=/usr/local/cargo
     fi && \
     mkdir -p /artifacts && \
     if [ "$BUILD_TARGET" = "engine" ]; then \
-        cargo build --bin rivet-engine $CARGO_FLAG --target aarch64-unknown-linux-gnu && \
+        cargo build -p rivet-engine --bin rivet-engine $CARGO_FLAG --target aarch64-unknown-linux-gnu && \
         cp target/aarch64-unknown-linux-gnu/$PROFILE_DIR/rivet-engine /artifacts/rivet-engine-aarch64-unknown-linux-gnu; \
     elif [ "$BUILD_TARGET" = "rivetkit-napi" ]; then \
         cd rivetkit-typescript/packages/rivetkit-napi && \

docker/build/linux-arm64-musl.Dockerfile

@@ -28,6 +28,7 @@ COPY . .
 RUN if [ "$BUILD_TARGET" = "engine" ] && [ "$BUILD_FRONTEND" = "true" ]; then \
         export NODE_OPTIONS="--max-old-space-size=8192" && \
         export SKIP_NAPI_BUILD=1 && \
+        export SKIP_WASM_BUILD=1 && \
         pnpm install --ignore-scripts && \
         VITE_APP_API_URL="${VITE_APP_API_URL}" VITE_FEATURE_FLAGS="${VITE_FEATURE_FLAGS}" npx turbo build -F @rivetkit/engine-frontend; \
     fi
@@ -56,7 +57,7 @@ RUN --mount=type=cache,id=cargo-registry-linux-arm64-musl,target=/usr/local/carg
     mkdir -p /artifacts && \
     if [ "$BUILD_TARGET" = "engine" ]; then \
         RUSTFLAGS="--cfg tokio_unstable -C target-feature=+crt-static -C link-arg=-static-libgcc" \
-            cargo build --bin rivet-engine $CARGO_FLAG --target aarch64-unknown-linux-musl && \
+            cargo build -p rivet-engine --bin rivet-engine $CARGO_FLAG --target aarch64-unknown-linux-musl && \
         cp target/aarch64-unknown-linux-musl/$PROFILE_DIR/rivet-engine /artifacts/rivet-engine-aarch64-unknown-linux-musl; \
     elif [ "$BUILD_TARGET" = "rivetkit-napi" ]; then \
         cd rivetkit-typescript/packages/rivetkit-napi && \

docker/build/linux-x64-gnu.Dockerfile

@@ -31,6 +31,7 @@ COPY . .
 RUN if [ "$BUILD_TARGET" = "engine" ] && [ "$BUILD_FRONTEND" = "true" ]; then \
         export NODE_OPTIONS="--max-old-space-size=8192" && \
         export SKIP_NAPI_BUILD=1 && \
+        export SKIP_WASM_BUILD=1 && \
         pnpm install --ignore-scripts && \
         VITE_APP_API_URL="${VITE_APP_API_URL}" VITE_FEATURE_FLAGS="${VITE_FEATURE_FLAGS}" npx turbo build -F @rivetkit/engine-frontend; \
     fi
@@ -59,7 +60,7 @@ RUN --mount=type=cache,id=cargo-registry-linux-x64-gnu,target=/usr/local/cargo/r
     fi && \
     mkdir -p /artifacts && \
     if [ "$BUILD_TARGET" = "engine" ]; then \
-        cargo build --bin rivet-engine $CARGO_FLAG --target x86_64-unknown-linux-gnu && \
+        cargo build -p rivet-engine --bin rivet-engine $CARGO_FLAG --target x86_64-unknown-linux-gnu && \
         cp target/x86_64-unknown-linux-gnu/$PROFILE_DIR/rivet-engine /artifacts/rivet-engine-x86_64-unknown-linux-gnu; \
     elif [ "$BUILD_TARGET" = "rivetkit-napi" ]; then \
         cd rivetkit-typescript/packages/rivetkit-napi && \

docker/build/linux-x64-musl.Dockerfile

@@ -27,6 +27,7 @@ COPY . .
 RUN if [ "$BUILD_TARGET" = "engine" ] && [ "$BUILD_FRONTEND" = "true" ]; then \
         export NODE_OPTIONS="--max-old-space-size=8192" && \
         export SKIP_NAPI_BUILD=1 && \
+        export SKIP_WASM_BUILD=1 && \
         pnpm install --ignore-scripts && \
         VITE_APP_API_URL="${VITE_APP_API_URL}" VITE_FEATURE_FLAGS="${VITE_FEATURE_FLAGS}" npx turbo build -F @rivetkit/engine-frontend; \
     fi
@@ -55,7 +56,7 @@ RUN --mount=type=cache,id=cargo-registry-linux-x64-musl,target=/usr/local/cargo/
     mkdir -p /artifacts && \
     if [ "$BUILD_TARGET" = "engine" ]; then \
         RUSTFLAGS="--cfg tokio_unstable -C target-feature=+crt-static -C link-arg=-static-libgcc" \
-            cargo build --bin rivet-engine $CARGO_FLAG --target x86_64-unknown-linux-musl && \
+            cargo build -p rivet-engine --bin rivet-engine $CARGO_FLAG --target x86_64-unknown-linux-musl && \
         cp target/x86_64-unknown-linux-musl/$PROFILE_DIR/rivet-engine /artifacts/rivet-engine-x86_64-unknown-linux-musl; \
     elif [ "$BUILD_TARGET" = "rivetkit-napi" ]; then \
         cd rivetkit-typescript/packages/rivetkit-napi && \

docker/build/windows-x64.Dockerfile

@@ -35,6 +35,7 @@ COPY . .
 RUN if [ "$BUILD_TARGET" = "engine" ] && [ "$BUILD_FRONTEND" = "true" ]; then \
         export NODE_OPTIONS="--max-old-space-size=8192" && \
         export SKIP_NAPI_BUILD=1 && \
+        export SKIP_WASM_BUILD=1 && \
         pnpm install --ignore-scripts && \
         VITE_APP_API_URL="${VITE_APP_API_URL}" VITE_FEATURE_FLAGS="${VITE_FEATURE_FLAGS}" npx turbo build -F @rivetkit/engine-frontend; \
     fi
@@ -62,7 +63,7 @@ RUN --mount=type=cache,id=cargo-registry-windows-x64,target=/usr/local/cargo/reg
     fi && \
     mkdir -p /artifacts && \
     if [ "$BUILD_TARGET" = "engine" ]; then \
-        cargo build --bin rivet-engine $CARGO_FLAG --target x86_64-pc-windows-gnu && \
+        cargo build -p rivet-engine --bin rivet-engine $CARGO_FLAG --target x86_64-pc-windows-gnu && \
         cp target/x86_64-pc-windows-gnu/$PROFILE_DIR/rivet-engine.exe /artifacts/rivet-engine-x86_64-pc-windows-gnu.exe; \
     elif [ "$BUILD_TARGET" = "rivetkit-napi" ]; then \
         cd rivetkit-typescript/packages/rivetkit-napi && \

docker/engine/Dockerfile

@@ -21,12 +21,13 @@ COPY . .
 # Build frontend. Use --ignore-scripts because the root postinstall runs
 # `lefthook install`, which needs a .git directory (excluded by
 # .dockerignore). lefthook is a dev-only git hook manager and has no
-# place inside the Docker build. SKIP_NAPI_BUILD=1 tells
-# @rivetkit/rivetkit-napi to skip its napi build. The frontend only
-# consumes the TypeScript surface, not the runtime .node binary.
+# place inside the Docker build. SKIP_NAPI_BUILD=1 and SKIP_WASM_BUILD=1 tell
+# the runtime binding packages to skip native artifact builds. The frontend only
+# consumes their TypeScript surfaces, not the runtime binaries.
 RUN if [ "$BUILD_FRONTEND" = "true" ]; then \
         export NODE_OPTIONS="--max-old-space-size=8192" && \
         export SKIP_NAPI_BUILD=1 && \
+        export SKIP_WASM_BUILD=1 && \
         pnpm install --ignore-scripts && \
         VITE_APP_API_URL="${VITE_APP_API_URL}" VITE_FEATURE_FLAGS="${VITE_FEATURE_FLAGS}" VITE_APP_TURNSTILE_SITE_KEY="${VITE_APP_TURNSTILE_SITE_KEY}" npx turbo build -F @rivetkit/engine-frontend; \
     fi
@@ -40,9 +41,9 @@ RUN \
     --mount=type=cache,target=/app/target,id=univseral-target \
     --mount=type=cache,target=/root/.cache,id=universal-user-cache \
     if [ "$CARGO_BUILD_MODE" = "release" ]; then \
-        RUSTFLAGS="--cfg tokio_unstable" cargo build --bin rivet-engine --release; \
+        RUSTFLAGS="--cfg tokio_unstable" cargo build -p rivet-engine --bin rivet-engine --release; \
     else \
-        RUSTFLAGS="--cfg tokio_unstable" cargo build --bin rivet-engine; \
+        RUSTFLAGS="--cfg tokio_unstable" cargo build -p rivet-engine --bin rivet-engine; \
     fi && \
     # cargo install --locked tokio-console && \
     mkdir /app/dist/ && \