chore: rivetkit core/napi/typescript follow up review

[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

[railway-app]

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

Service	Status	Web	Updated (UTC)
kitchen-sink	❌ Build Failed (View Logs)	Web	Apr 23, 2026 at 11:24 pm
website	😴 Sleeping (View Logs)	Web	Apr 23, 2026 at 3:00 pm
frontend-cloud	❌ Build Failed (View Logs)	Web	Apr 23, 2026 at 9:55 am
ladle	✅ Success (View Logs)	Web	Apr 23, 2026 at 9:55 am
frontend-inspector	❌ Build Failed (View Logs)	Web	Apr 23, 2026 at 9:54 am
mcp-hub	✅ Success (View Logs)	Web	Apr 23, 2026 at 3:55 am

[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

• chore(rivetkit): impl follow up review #4711
• chore: rivetkit core/napi/typescript follow up review #4702 👈 (View in Graphite)
• chore: fix remaining issues with rivetkit-core #4701
• feat: import/export actors #4640
• chore: sqlite v1 to v2 data migration #4692
• 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]

PR 4702 Code Review — Adversarial Review Synthesis

The full adversarial review findings (F1-F42) with challenger verdicts are in this comment. The per-diff code review is in the comment below.

Key findings verified as REAL in this PR:

• F3: clean run exit fix (task.rs) - FIXED in this PR
• F12: Registry.handler()/serve() throw - spec written (handler-serve-restoration.md), fix pending
• F14: package exports subpaths removed - ./db and ./db/drizzle restored in this PR
• F18: actor-lifecycle state in napi not core - tracked, not yet fixed
• F19: inspector logic duplicated in TypeScript - tracked, not yet fixed
• F21: 50ms polling loop in native.ts - tracked, not yet fixed
• F32: module-level actor-keyed maps in native.ts - tracked, not yet fixed
• F34: ActorContext.key type widened - tracked, not yet fixed
• F35: sql on ctx but ./db dropped - ./db/drizzle restored in this PR
• F36: ContextOf type helpers removed - tracked for restoration
• F38: inline use in test - tracked
• F41: dead BARE code audit - pending audit
• F42: inline mod tests in src/ - policy added to CLAUDE.md

[claude]

PR Review: rivetkit core/napi/typescript follow up

Overview

This PR delivers a large follow-up cleanup across rivetkit-core (Rust), rivetkit-napi, and rivetkit-typescript. Key additions: a new serverless.rs runtime for serverless request handling, a runner_config.rs helper for local dev auto-configuration, a lifecycle fix for clean actor exit, and various TypeScript/test improvements.

---

Critical Issues

1. task.rs: Early return skips cleanup when actor exits cleanly while Started

File: rivetkit-rust/packages/rivetkit-core/src/actor/task.rs

When an actor run handler exits cleanly before the engine sends Stop, the early return None bypasses reset_sleep_timer(), state_save_deadline = None, inspector_serialize_state_deadline = None, and close_actor_event_channel(). State-save and inspector timers remain armed and may fire on dead channels while the task idles waiting for Stop. The cleanup calls must execute unconditionally before the early return so timers are disarmed on every exit path.

2. configure.ts: Silent error swallowing on a required startup path

File: rivetkit-typescript/packages/rivetkit/src/serverless/configure.ts

The catch block logs and silently returns undefined. CLAUDE.md fail-by-default: required startup paths must throw so callers can abort. Swallowing the error means misconfiguration goes undetected until actors fail to route in production.

3. native.ts: restartRunHandler/setAlarm wrapping drops the NAPI Promise

File: rivetkit-typescript/packages/rivetkit/src/registry/native.ts

Before: callNative(() => this.#ctx.restartRunHandler())

After: callNative(async () => { this.#ctx.restartRunHandler(); })

The new async wrapper discards the inner return value. If the NAPI methods return a Promise, the outer async function resolves immediately without awaiting it - a silent fire-and-forget. Add await inside the wrapper, or revert to the single-expression form.

---

Medium Issues

4. serverless.rs: SSE start loop never emits a completion event

File: rivetkit-rust/packages/rivetkit-core/src/serverless.rs

After start_serverless_actor returns Ok, no success event is written; the loop only sends pings until cancellation. The client cannot distinguish "actor running" from "still starting". An event: started frame should be emitted before entering the ping loop.

5. runner_config.rs: Unconditional call can overwrite a serverless pool config

File: rivetkit-rust/packages/rivetkit-core/src/registry/mod.rs

ensure_local_normal_runner_config is called unconditionally in CoreRegistry::start(), before into_serverless_runtime() is reached. A serverless registry pointing at a local engine will PUT a normal-runner config and potentially clobber the serverless pool config. Gate this call on the non-serverless topology path.

6. native.ts: Plain Error thrown on a required lifecycle path

CLAUDE.md requires RivetError at all boundaries. The throw new Error for missing client config should use the structured error type.

7. runner_config.rs: No retry/backoff when local engine is still warming up

If the engine is not yet ready when CoreRegistry::start() calls ensure_local_normal_runner_config, the PUT fails and startup aborts entirely. A brief retry with backoff or gating on engine health would make local dev resilient to the natural startup race.

---

Style / Convention

8. @ts-nocheck in test files - masks real type errors; fix types instead of suppressing.

9. vi.waitFor timeout additions ({ timeout: 10_000, interval: 25 } in actor-conn.test.ts) - acceptable short-term but per CLAUDE.md each should document why the race exists or link a ticket.

---

Positive Observations

• Constant-time token comparison in serverless.rs via subtle::ConstantTimeEq - correct security practice.
• TokioMutex used throughout serverless.rs; no std::sync::Mutex in async context.
• Structured tracing logging with named fields throughout the new Rust code.
• CORS applied uniformly in both success and error paths in serverless.rs.
• Error types in serverless.rs use #[derive(rivet_error::RivetError)] correctly.
• isClosedTaskRegistrationError defensive metadata access fix in native.ts is a solid improvement.

---

Summary - must-fix before merge

1. task.rs - disarm timers and close channel before the early return on clean exit.
2. configure.ts - throw (or remove the catch) on serverless pool configuration failure.
3. native.ts restartRunHandler/setAlarm - await the NAPI call or revert to single-expression form.
4. serverless.rs SSE - emit a started/success event so the client has a protocol contract.

🤖 Generated with Claude Code

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4702

All packages published as 0.0.0-pr.4702.76b6c25 with tag pr-4702.

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-76b6c25
docker pull rivetdev/engine:full-76b6c25

Individual packages

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

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4702

All packages published as 0.0.0-pr.4702.d108c6a with tag pr-4702.

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-d108c6a
docker pull rivetdev/engine:full-d108c6a

Individual packages

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