feat(pb): actors v3

[MasterPtato]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[railway-app]

🚅 Deployed to the rivet-pr-4463 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
frontend-cloud	😴 Sleeping (View Logs)	Web	Mar 23, 2026 at 6:52 pm
frontend-inspector	😴 Sleeping (View Logs)	Web	Mar 23, 2026 at 6:38 pm
website	😴 Sleeping (View Logs)	Web	Mar 23, 2026 at 6:34 pm
mcp-hub	✅ Success (View Logs)	Web	Mar 21, 2026 at 1:56 am
ladle	❌ Build Failed (View Logs)	Web	Mar 21, 2026 at 1:56 am

[MasterPtato]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat(pb): actors v3 #4463 👈 (View in Graphite)
• feat(cache): add in flight deduping #4459
• fix(cache): clean up lib #4457
• fix(config): allow configuring topo dcs via map, fix pg ssl mode config #4456
• fix(api): dont 500 on cross dc response #4449
• chore: update byte units on frontend #4444
• fix: runner alloc idx logic, api auth for actor get #4443
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[pkg-pr-new]

More templates

• actor-actions
• actor-actions-vercel
• ai-agent
• ai-agent-vercel
• example-ai-and-user-generated-actors-freestyle
• chat-room
• chat-room-vercel
• example-cloudflare-workers
• example-cloudflare-workers-hono
• collaborative-document
• collaborative-document-vercel
• cross-actor-actions
• cross-actor-actions-vercel
• example-cursors
• example-cursors-raw-websocket
• example-cursors-raw-websocket-vercel
• example-cursors-vercel
• custom-serverless
• example-elysia
• example-experimental-durable-streams-ai-agent
• example-experimental-durable-streams-ai-agent-vercel
• geo-distributed-database
• geo-distributed-database-vercel
• hello-world
• hello-world-vercel
• example-hono
• hono-react
• hono-react-vercel
• example-kitchen-sink
• example-kitchen-sink-vercel
• multi-region-vercel
• multiplayer-game
• example-multiplayer-game-patterns
• example-multiplayer-game-patterns-vercel
• multiplayer-game-vercel
• native-websockets
• native-websockets-vercel
• next-js
• per-tenant-database
• per-tenant-database-vercel
• example-raw-fetch-handler
• example-raw-fetch-handler-vercel
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-raw-websocket-handler-proxy-vercel
• example-raw-websocket-handler-vercel
• example-react
• example-react-vercel
• sandbox
• sandbox-coding-agent
• sandbox-coding-agent-vercel
• sandbox-vercel
• scheduling
• scheduling-vercel
• example-sqlite-drizzle
• example-sqlite-raw
• state
• state-vercel
• example-stream
• example-stream-vercel
• example-trpc

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@4463

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@4463

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@4463

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@4463

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@4463

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@4463

@rivetkit/sqlite-vfs

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sqlite-vfs@4463

@rivetkit/traces

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/traces@4463

@rivetkit/workflow-engine

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/workflow-engine@4463

@rivetkit/virtual-websocket

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/virtual-websocket@4463

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@4463

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@4463

commit: 3f2996f

[claude]

PR Review: feat(pb): actors v3

Note: This is a draft PR. Review focuses on issues that should be resolved before merging.

Critical Issues

1. Struct name mismatch (compile error)
In engine/packages/guard/src/routing/envoy.rs, the routing code references pegboard_envoy::PegboardEnvoyWsCustomServe, but engine/packages/pegboard-envoy/src/lib.rs only defines PegboardRunnerWsCustomServe. This would fail to compile.

2. Syntax errors in actor2 workflow (compile errors)
In the actor2 workflow, two issues exist: } else if Some(alarm_ts) = state.alarm_ts { is missing let, and let lifecycle_sttate = ... has a typo (sttate) while lifecycle_state is then used as an undefined variable.

3. Package name mismatch
engine/packages/pegboard-envoy/Cargo.toml declares name = pegboard-runner but the directory is pegboard-envoy. The name should match the directory.

Dependency Issues

4. Pinned hyper version outside workspace
Both pegboard-envoy and pegboard-gateway2 pin hyper = 1.6 with comments acknowledging the workspace version is not being used. These should be resolved before merging.

[claude]

Design / Logic Issues

5. Double-counted eviction metrics
Both tunnel_to_ws_task and ws_to_tunnel_task subscribe to separate eviction subjects and each increments EVICTION_TOTAL. When a runner is evicted, both tasks fire concurrently, doubling the counter per eviction.

6. Silent JSON deserialization errors in conn.rs
Actor metadata falls back to an empty map on parse failure via unwrap_or_default(). This silently swallows invalid data. At minimum, log a warning when falling back.

7. Wrong field mapping in Mk1 KV metadata
In the ws_to_tunnel_task.rs Mk1 handler, create_ts: x.update_ts looks like the wrong field is being mapped. It should likely be x.create_ts.

8. Unverified abort safety in demuxer GC
In actor_event_demuxer.rs, a TODO: Verify aborting is safe here precedes channel.handle.abort(). Aborting mid-dispatch could silently drop in-flight events. Confirm safety or use a graceful shutdown channel like shutdown() uses.

[claude]

Code Quality

9. Significant KV code duplication
handle_message_mk1 and handle_message_mk2 in ws_to_tunnel_task.rs share nearly identical KV operation handling (~400 lines), repeated for each operation type. Consider extracting a shared dispatcher that converts protocol versions once and delegates to common logic.

10. Unimplemented module
engine/packages/pegboard/src/workflows/actor2/allocator.rs is an empty file. Either add a placeholder comment or remove it until it has content.

11. TODOs indicating known gaps
The queue/bg-thread TODO means KV ops run inline in the WebSocket message loop, which could block message handling under load. The do-not-return-actual-error TODO means internal error details are exposed directly to runners in KV responses.

Minor / Style

12. Workflow rename is a breaking change
In engine/packages/pegboard/src/workflows/actor/metrics.rs, renaming from pegboard_actor_metrics to pegboard_actor2_metrics affects in-flight executions. Confirm this is intentional and that any migration path has been handled.

[claude]

Summary

This is a substantial feature adding an envoy abstraction layer between runners and the engine, plus a v2 gateway and the foundations of an actors v3 workflow. The overall architecture looks solid. The eviction, hibernation, and ping/keepalive mechanics are well-designed with good attention to race conditions (subscribe before publish for eviction, structured lifecycle abort pattern, etc.).

Before marking ready for review, the compile errors (items 1-3) must be fixed. Items 5, 7, and 8 are the highest-priority logic issues.