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,44 @@ 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
+      - 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 +336,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 +382,11 @@ 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: Place native binaries in platform packages
         run: |
@@ -397,7 +441,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

rivetkit-typescript/packages/rivetkit-wasm/scripts/build.mjs

@@ -1,5 +1,27 @@
 #!/usr/bin/env node
 import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const pkgDir = join(packageDir, "pkg");
+
+if (["1", "true"].includes(process.env.SKIP_WASM_BUILD ?? "")) {
+	const requiredFiles = [
+		"rivetkit_wasm.js",
+		"rivetkit_wasm.d.ts",
+		"rivetkit_wasm_bg.wasm",
+	];
+	const missingFiles = requiredFiles.filter((file) => !existsSync(join(pkgDir, file)));
+	if (missingFiles.length > 0) {
+		throw new Error(
+			`SKIP_WASM_BUILD is set but pkg is incomplete: ${missingFiles.join(", ")}`,
+		);
+	}
+	console.log("[rivetkit-wasm/build] using existing pkg artifact");
+	process.exit(0);
+}
 
 const args = process.argv.slice(2);
 const targetIndex = args.indexOf("--target");

scripts/ralph/prd.json

@@ -398,7 +398,7 @@
         "Typecheck passes"
       ],
       "priority": 23,
-      "passes": false,
+      "passes": true,
       "notes": ""
     }
   ]

scripts/ralph/progress.txt

@@ -276,3 +276,13 @@ Started: Wed Apr 29 08:03:50 PM PDT 2026
   - Public `c.sql` write forcing goes through `writeMode(() => c.sql.execute(...))`; the lower runtime adapter maps that to `executeWrite`.
   - `@rivetkit/rivetkit-wasm/pkg/` is generated, so host smoke tests should not require importing the real package until the wasm-pack output exists in the test environment.
 ---
+## 2026-04-29 23:26:43 PDT - US-023
+- Documented the implemented remote SQLite and wasm runtime invariants in `.agent/specs/rivetkit-core-wasm-support.md`.
+- Refreshed stale current-state notes so the spec records v4-only remote SQL rollout behavior, wasm remote-only SQLite, lazy pegboard-envoy SQL executors, envoy-client transport ownership, lost-response behavior, and the direct wasm-bindgen binding strategy.
+- Files changed: `.agent/specs/rivetkit-core-wasm-support.md`, `scripts/ralph/prd.json`, `scripts/ralph/progress.txt`.
+- Quality checks: `scripts/cargo/check-rivetkit-core-wasm.sh`.
+- **Learnings for future iterations:**
+  - Keep high-level wasm and remote SQLite decisions in the spec's implemented invariants section so future changes do not have to reconstruct them from individual story logs.
+  - The wasm support spec should reflect the current gate command instead of stale one-off compile probes.
+  - Remote SQL lost-response behavior is now a decided invariant: sent requests fail with `sqlite.remote_indeterminate_result`, while only unsent requests can be sent after reconnect.
+---

turbo.json

@@ -13,7 +13,7 @@
 				"package.json"
 			],
 			"outputs": ["dist/**"],
-			"env": ["FAST_BUILD", "SKIP_NAPI_BUILD"]
+			"env": ["FAST_BUILD", "SKIP_NAPI_BUILD", "SKIP_WASM_BUILD"]
 		},
 		"build:ladle": {
 			"dependsOn": ["^build"],