fix(rivetkit-core): gate startup until runtime is ready

[NathanFlurry]

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

[NathanFlurry]

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

• fix(rivetkit-core): gate startup until runtime is ready #4736 : 2 dependent PRs (#4737 , #4739 ) 👈 (View in Graphite)
• fix(rivetkit-sqlite): preserve text with embedded nul bytes #4735
• chore(rivetkit): add child spans for logging #4734
• fix(rivetkit-core): orphan engine process and detect crashes #4733
• fix(rivetkit-core): return None for empty inspector state to avoid frontend CBOR decode error #4732
• fix(rivetkit-core): don't install tokio::signal::ctrl_c() handler inside serve_with_config #4731
• refactor(rivetkit-core): use subtle::ConstantTimeEq for inspector token verify #4730
• fix(rivetkit): drop is_read_only_sql classifier, surface RETURNING rows #4728
• docs: require close-code rejection for websocket auth/policy failures #4727
• fix(rivetkit): inspector reports actual config state + real queue messages #4726
• fix(rivetkit-napi): plumb ctx through serializeState TSF and stop panicking on runtime_state Ref drop #4725
• chore(rivetkit): remove legacy metrics & prometheus auth #4724
• chore(rivetkit): remove legacy metrics #4723
• chore(rivetkit): impl inspector token #4722
• chore: disable auth on serverless #4721
• chore: fix cors for envoys #4720
• chore: fix serverless in rivetkit-core #4719
• chore(rivetkit): impl follow up review #4711
• chore: rivetkit core/napi/typescript follow up review #4702
• chore: fix remaining issues with rivetkit-core #4701
• chore: sqlite v1 to v2 data migration #4692 : 1 other dependent PR (#4640 )
• chore: move rivetkit to task model #4680
• chore: rivetkit to rust #4679
• feat(rivetkit): sqlite vfs v2 #4673
• chore: rename sandbox -> kitchen sink #4671 : 1 other dependent PR (#4672 )
• chore: configure TLS trust roots for rustls clients #4667
• fix(rivetkit): update config to match envoys & remove manager references #4663
• chore(publish): pin docker base image refs #4652
• chore(engine): publish engine bases in ci #4649 : 2 other dependent PRs (#4650 , #4666 )
• chore: lockfile lefthook #4647
• fix(rivetkit): surface native sqlite kv errors to callers #4645
• fix(rivetkit): prevent sleep races during disconnect and db work #4644
• fix(rivetkit): isolate engine envoys and propagate startup failures #4643
• test(rivetkit): remove wasm sqlite-only fixtures and coverage #4642
• chore(sqlite-vfs): remove wasm sqlite packages and workspace wiring #4641
• chore(rivetkit): remove wasm sqlite runtime #4614
• fix(sqlite-native): restore native startup kv preload #4639
• fix(sqlite-native): delete metadata before chunk range #4638
• fix(sqlite-native): keep truncate cache coherent #4637
• fix(sqlite-vfs): use delete range for truncate cleanup #4636
• fix(sqlite-native): restore kv error hook #4635
• perf(sqlite-native): avoid cloning cached read chunks #4634
• perf(sqlite-native): gate kv operation labels #4633
• perf(sqlite-native): reuse read cache for partial writes #4632
• perf(sqlite-native): remove delete file existence probe #4631
• fix(sqlite-native): gate native read cache behind env var #4630
• fix(pegboard): isolate runner config dc lookup failures #4625 : 1 other dependent PR (#4626 )
• docs(pegboard): note runner config upsert split write risk #4624
• fix(pegboard): unpack global runner config keys correctly #4623
• fix(pegboard-gateway): enforce tunnel message state #4622
• fix(pegboard-runner): clear terminal tunnel routes #4621
• fix(pegboard): skip protocol version keys in runner pool backfill #4620
• fix(pegboard): create missing normal runner configs #4619
• fix(epoxy): reuse cached optimistic value #4618
• main

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

[claude]

Review: fix(rivetkit-core): gate startup until runtime is ready

Overview

This PR fixes a race condition where client requests could be dispatched to an actor that has not finished its startup sequence (i.e., onInitialize has not completed). It introduces a new actor.starting error, returns proper errors from active_actor for both pre-ready and stopping actors, and teaches the TypeScript client to retry on this new error code.

---

What is correct and well-done

• The core fix is sound. Checking instance.ctx.ready() before handing out the instance prevents a whole class of race conditions where requests land on an actor mid-initialization.
• Stopping state behavior fix. The old active_actor silently returned a stopping instance (with a warning). Returning a proper error code and having the client re-resolve via query target is strictly better behavior.
• HTTP dispatch refactoring is clean. Computing framework_http_route before active_actor so the error response can be encoded in the correct format (message_boundary_error_response vs. inspector_anyhow_response) is the right separation.
• Client retry symmetry. Treating starting identically to stopping in the invalidation and retry paths of actor-handle.ts and actor-query.ts is consistent.

---

Issues and suggestions

1. Missing newline at EOF in actor.starting.json

All other JSON artifact files end with a newline; this one does not. Should add a trailing newline.

2. Unrelated pnpm dependency (@rivetkit/sql-loader@2.2.1)

The pnpm-lock.yaml change adds @rivetkit/sql-loader to the rivetkit package. This appears unrelated to the startup-gating fix and should be in a separate PR or explained in the description.

3. No tests for the new Starting error path

The lifecycle and registry tests in rivetkit-rust/packages/rivetkit-core/tests/modules/ have no coverage for the case where active_actor is called while the actor is in Loading state. A test that (1) spawns an actor with a slow onInitialize, (2) issues a request concurrently, and (3) asserts the actor.starting error is returned would prevent regressions. This matters because active_actor is also used by the WebSocket path (registry/websocket.rs:23), which propagates the error via ?.

4. Active + not ready + destroy_requested edge case

When an actor is in ActorInstanceState::Active but !ready() and destroy_requested(), the code returns Destroying. This appears correct (actor destroyed during initialization), but a short comment explaining the state combination would help future readers since it is non-obvious.

5. Hardcoded 100 ms delay inconsistency in actor-handle.ts

At line ~351 (the WebSocket retry path), starting and stopping use a raw setTimeout(resolve, 100). The other retry sites all use #waitForRetryWindow. This was pre-existing for stopping but is now extended to starting. Consider unifying to #waitForRetryWindow or documenting why this path uses a different delay.

6. WebSocket path propagates Starting without explicit close-frame handling

handle_websocket propagates the active_actor error via ?. Per the CLAUDE.md convention, WebSocket rejections should carry a meaningful close code and group.code reason. Confirm the calling layer converts this anyhow::Error into a proper close frame (close code 1008, reason actor.starting) so browser clients get diagnostic info.

---

Summary

The fix is correct and addresses a real race condition. The main gaps before merging are a test covering the Loading-state rejection, resolving the unrelated lock-file change, and a trailing newline in the artifact file. The delay inconsistency and WebSocket close-frame question are lower priority.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4736

All packages published as 0.0.0-pr.4736.ed96c00 with tag pr-4736.

Engine binary is shipped via @rivetkit/engine-cli on linux-x64-musl, linux-arm64-musl, darwin-x64, and darwin-arm64. Windows users should use the release installer or set RIVET_ENGINE_BINARY.

Docker images:

docker pull rivetdev/engine:slim-ed96c00
docker pull rivetdev/engine:full-ed96c00

Individual packages

npm install rivetkit@pr-4736
npm install @rivetkit/react@pr-4736
npm install @rivetkit/rivetkit-napi@pr-4736
npm install @rivetkit/workflow-engine@pr-4736