chore(kitchen-sink): add rivet cloud deploy workflow

.claude/skills/sanity-check/SKILL.md

@@ -15,7 +15,10 @@ Run a quick end-to-end sanity check of a published rivetkit version: copy the he
 
 ## Inputs
 1. **Version or tag** (required) — explicit pkg-pr-new preview, npm dist-tag, or semver. If not provided in the user's message, ask for it.
-2. **Additional test behavior** (optional) — e.g., "also verify workflows persist" or "check that KV works." If provided, extend `src/index.ts` + `test.mjs` using the menu in "Extending with custom tests" below.
+2. **Engine mode** (optional, defaults to bundled) — the hello-world example's `registry.start()` only spawns the bundled engine binary when `RIVET_RUN_ENGINE=1` is set. Without it, the runtime boots in serverful mode and immediately fails trying to connect to a non-existent engine at `:6420` (`get local datacenters` → `Connection refused`).
+   - **bundled engine** (default): export `RIVET_RUN_ENGINE=1` before `node test.mjs`. Pairs the published `@rivetkit/engine-cli` binary with the published `rivetkit` runtime — what you want for end-to-end version verification.
+   - **external engine**: only use if the user explicitly says they have their own engine already running on `:6420` (e.g. `self-host/compose/dev`). Do not set the env var.
+3. **Additional test behavior** (optional) — e.g., "also verify workflows persist" or "check that KV works." If provided, extend `src/index.ts` + `test.mjs` using the menu in "Extending with custom tests" below.
 
 ## Usage
 - `/sanity-check <version>` — run in a temp directory on the host
@@ -151,22 +154,25 @@ try {
 
 ### 3. Install + run
 
-**Default (host):**
+**Default (host, bundled engine):**
 ```bash
 cd "$SANITY_DIR"
 npm install
-node test.mjs
+RIVET_RUN_ENGINE=1 node test.mjs
 ```
 
+Drop `RIVET_RUN_ENGINE=1` only if the user explicitly said they're running an external engine on `:6420`.
+
 If you need to inspect a failure after the fact, tee the output:
 ```bash
-node test.mjs 2>&1 | tee /tmp/sanity-check.log
+RIVET_RUN_ENGINE=1 node test.mjs 2>&1 | tee /tmp/sanity-check.log
 echo "exit=$?"
 ```
 
 **Docker mode:**
 ```bash
 docker run --rm \
+  -e RIVET_RUN_ENGINE=1 \
   -v "$SANITY_DIR":/app \
   -w /app \
   node:22 \

.github/workflows/rivet-deploy-kitchen-sink.yml

@@ -0,0 +1,97 @@
+name: Rivet Deploy (kitchen-sink)
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+    paths:
+      - "examples/kitchen-sink/**"
+      - "rivetkit-typescript/packages/**"
+      - "engine/sdks/typescript/**"
+      - "shared/typescript/**"
+      - "docker/build/linux-x64-gnu.Dockerfile"
+      - ".github/workflows/rivet-deploy-kitchen-sink.yml"
+  push:
+    branches: [main]
+    paths:
+      - "examples/kitchen-sink/**"
+      - "rivetkit-typescript/packages/**"
+      - "engine/sdks/typescript/**"
+      - "shared/typescript/**"
+      - "docker/build/linux-x64-gnu.Dockerfile"
+      - ".github/workflows/rivet-deploy-kitchen-sink.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: rivet-deploy-kitchen-sink-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  rivet-deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Build rivetkit-napi .node (linux-x64-gnu)
+        env:
+          DEPOT_TOKEN: ${{ secrets.DEPOT_TOKEN }}
+        run: |
+          set -euo pipefail
+          # The DEPOT_TOKEN enables sccache; the Dockerfile gracefully falls
+          # back to a no-cache build if it isn't set.
+          DEPOT_TOKEN_FILE=$(mktemp)
+          printf "%s" "${DEPOT_TOKEN:-}" > "${DEPOT_TOKEN_FILE}"
+          docker buildx build \
+            --file docker/build/linux-x64-gnu.Dockerfile \
+            --build-arg BUILD_TARGET=rivetkit-napi \
+            --build-arg BUILD_MODE=release \
+            --secret id=DEPOT_TOKEN,src="${DEPOT_TOKEN_FILE}" \
+            --load \
+            --tag rivetkit-napi-builder:local \
+            .
+          rm -f "${DEPOT_TOKEN_FILE}"
+          container_id=$(docker create rivetkit-napi-builder:local)
+          docker cp "${container_id}:/artifacts/rivetkit-napi.linux-x64-gnu.node" \
+            ./examples/kitchen-sink/rivetkit-napi.linux-x64-gnu.node
+          docker rm "${container_id}" >/dev/null
+          ls -lh ./examples/kitchen-sink/rivetkit-napi.linux-x64-gnu.node
+      - name: Collect workspace manifest stubs
+        run: |
+          set -euo pipefail
+          # pnpm deploy resolves the full workspace topology even when filtered,
+          # so it needs every workspace package.json that isn't already in the
+          # Dockerfile's COPY set. Collect them under a single dir that the
+          # Dockerfile copies AFTER pnpm install/build (so install isn't
+          # tempted to walk them).
+          rm -rf .docker-ks-manifests
+          mkdir -p .docker-ks-manifests
+          find . -type f -name 'package.json' \
+            -not -path './node_modules/*' \
+            -not -path '*/node_modules/*' \
+            -not -path './target/*' \
+            -not -path './.git/*' \
+            -not -path './.docker-ks-manifests/*' \
+            -not -path './napi-artifacts/*' \
+            -not -path './package.json' \
+            -not -path './examples/kitchen-sink/*' \
+            -not -path './rivetkit-typescript/packages/*' \
+            -not -path './engine/sdks/typescript/*' \
+            -not -path './shared/typescript/*' \
+            -print0 |
+          while IFS= read -r -d '' src; do
+            rel="${src#./}"
+            dest=".docker-ks-manifests/${rel}"
+            mkdir -p "$(dirname "${dest}")"
+            cp "${src}" "${dest}"
+          done
+          echo "manifest stubs:"
+          find .docker-ks-manifests -name package.json | sort
+      - uses: rivet-dev/deploy-action@v1.1.0
+        with:
+          rivet-token: ${{ secrets.KITCHEN_SINK_RIVET_CLOUD_TOKEN }}
+          dockerfile-path: examples/kitchen-sink/Dockerfile
+          docker-build-path: .
+          managed-pool-config: '{"environment":{"PORT":"8080"}}'

.gitignore

@@ -84,3 +84,7 @@ examples/*/public/
 
 # Ralph/Codex generated command stream logs
 scripts/ralph/codex-streams/
+
+# Kitchen-sink Rivet Cloud deploy build artifacts
+.docker-ks-manifests/
+examples/kitchen-sink/rivetkit-napi.*.node

CLAUDE.md

@@ -77,6 +77,10 @@ docker-compose up -d
 - We use Graphite for stacked PRs. Diff against the parent branch (`gt ls` to see the stack), not `main`.
 - To revert a file to the version before this branch's changes, checkout from the first child branch (below in the stack), not from `main` or the parent. Child branches contain the pre-this-branch state of files modified by branches further down the stack.
 
+### jj
+
+- Always invoke `jj diff` with `--git --color=never`. The jj-default format compresses unchanged context with `...` ellipses and uses a `<old> <new>:` line-number prefix that visually fuses with adjacent tokens, causing misreads (e.g. `tracing::debug!` → `tracing::info!` looked like a `debug!` → `debuginfo!` rename). The unified `diff --git` format has unambiguous `-`/`+` markers at column 0 and standard `@@` hunk headers.
+
 **Never push to `main` unless explicitly specified by the user.**
 
 ## Frontend Visual Changes

engine/packages/depot-client/src/database.rs

@@ -32,9 +32,10 @@ pub async fn open_database_from_transport(
 ) -> Result<NativeDatabaseHandle> {
 	let vfs_name = vfs_name_for_actor_database(&actor_id, generation);
 	let config = VfsConfig::default();
-	let initial_pages = fetch_initial_pages_for_registration(transport.clone(), &actor_id, &config)
-		.await
-		.map_err(|e| anyhow!("failed to preload sqlite pages: {e}"))?;
+	let initial_pages =
+		fetch_initial_pages_for_registration(transport.clone(), &actor_id, generation, &config)
+			.await
+			.map_err(|e| anyhow!("failed to preload sqlite pages: {e}"))?;
 	let vfs = Arc::new(
 		SqliteVfs::register_with_transport_and_initial_pages(
 			&vfs_name,

engine/packages/depot-client/src/optimization_flags.rs

@@ -23,11 +23,12 @@ pub const VFS_PAGE_CACHE_CAPACITY_PAGES_ENV: &str =
 	"RIVETKIT_SQLITE_OPT_VFS_PAGE_CACHE_CAPACITY_PAGES";
 pub const VFS_PROTECTED_CACHE_PAGES_ENV: &str = "RIVETKIT_SQLITE_OPT_VFS_PROTECTED_CACHE_PAGES";
 pub const VFS_STAGING_CACHE_TTL_MS_ENV: &str = "RIVETKIT_SQLITE_OPT_VFS_STAGING_CACHE_TTL_MS";
+pub const VFS_RETAIN_READ_CACHE_ENV: &str = "RIVETKIT_SQLITE_OPT_VFS_RETAIN_READ_CACHE";
 
 pub const DEFAULT_STARTUP_PRELOAD_MAX_BYTES: usize = 1024 * 1024;
-pub const MAX_STARTUP_PRELOAD_MAX_BYTES: usize = 8 * 1024 * 1024;
+pub const MAX_STARTUP_PRELOAD_MAX_BYTES: usize = 64 * 1024 * 1024;
 pub const DEFAULT_STARTUP_PRELOAD_FIRST_PAGE_COUNT: u32 = 1;
-pub const MAX_STARTUP_PRELOAD_FIRST_PAGE_COUNT: u32 = 256;
+pub const MAX_STARTUP_PRELOAD_FIRST_PAGE_COUNT: u32 = 16_384;
 pub const DEFAULT_VFS_PAGE_CACHE_CAPACITY_PAGES: u64 = 50_000;
 pub const MAX_VFS_PAGE_CACHE_CAPACITY_PAGES: u64 = 500_000;
 pub const DEFAULT_VFS_PROTECTED_CACHE_PAGES: usize = 512;
@@ -106,6 +107,7 @@ pub struct SqliteOptimizationFlags {
 	pub vfs_page_cache_capacity_pages: u64,
 	pub vfs_protected_cache_pages: usize,
 	pub vfs_staging_cache_ttl_ms: u64,
+	pub vfs_retain_read_cache: bool,
 }
 
 impl Default for SqliteOptimizationFlags {
@@ -133,6 +135,7 @@ impl Default for SqliteOptimizationFlags {
 			vfs_page_cache_capacity_pages: DEFAULT_VFS_PAGE_CACHE_CAPACITY_PAGES,
 			vfs_protected_cache_pages: DEFAULT_VFS_PROTECTED_CACHE_PAGES,
 			vfs_staging_cache_ttl_ms: DEFAULT_VFS_STAGING_CACHE_TTL_MS,
+			vfs_retain_read_cache: false,
 		}
 	}
 }
@@ -206,6 +209,9 @@ impl SqliteOptimizationFlags {
 				DEFAULT_VFS_STAGING_CACHE_TTL_MS,
 				MAX_VFS_STAGING_CACHE_TTL_MS,
 			),
+			vfs_retain_read_cache: disabled_by_default(
+				read_env(VFS_RETAIN_READ_CACHE_ENV).as_deref(),
+			),
 		}
 	}
 }
@@ -228,6 +234,20 @@ fn enabled_by_default(value: Option<&str>) -> bool {
 		_ => true,
 	}
 }
+
+fn disabled_by_default(value: Option<&str>) -> bool {
+	match value.map(|value| value.trim().to_ascii_lowercase()) {
+		Some(value)
+			if matches!(
+				value.as_str(),
+				"1" | "true" | "on" | "yes" | "enabled" | "enable"
+			) =>
+		{
+			true
+		}
+		_ => false,
+	}
+}
 fn usize_bounded_by_default(value: Option<&str>, default: usize, max: usize) -> usize {
 	value
 		.and_then(|value| value.trim().parse::<usize>().ok())
@@ -318,6 +338,7 @@ mod tests {
 			VFS_PAGE_CACHE_CAPACITY_PAGES_ENV => Some("0".to_string()),
 			VFS_PROTECTED_CACHE_PAGES_ENV => Some("0".to_string()),
 			VFS_STAGING_CACHE_TTL_MS_ENV => Some("0".to_string()),
+			VFS_RETAIN_READ_CACHE_ENV => Some("true".to_string()),
 			_ => None,
 		});
 
@@ -339,6 +360,7 @@ mod tests {
 		assert_eq!(flags.vfs_page_cache_capacity_pages, 0);
 		assert_eq!(flags.vfs_protected_cache_pages, 0);
 		assert_eq!(flags.vfs_staging_cache_ttl_ms, 0);
+		assert!(flags.vfs_retain_read_cache);
 	}
 
 	#[test]