fix(rivetkit-core): abort graceful cleanup task when grace deadline elapses

[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

• chore(envoy-client): log command and event payloads #4751
• fix(rivetkit): minor sleep-cleanup follow-ups #4761
• docs(rivetkit): clean up stale setPreventSleep references in docs and JSDoc #4760
• docs(rivetkit): document keepAwake/waitUntil counter-arm race and surface bridge errors #4759
• test(engine): force overdue branch in alarm-during-sleep test with negative offset #4758
• fix(rivetkit-core): return stopping not starting when sleep/destroy called mid-shutdown #4757
• test(rivetkit): remove sleepWithPreventSleep fixture and tests #4756
• test(engine): add regression test for alarm-during-sleep-transition race #4755
• test(rivetkit-core): cover sleep/destroy guards and prevent_sleep no-op #4750
• docs: add keepAwake vs waitUntil table and internal sleep-sequence invariants #4749
• feat(rivetkit): expose c.keepAwake(promise) through native path #4748
• refactor(rivetkit): deprecate setPreventSleep to no-op in TypeScript #4747
• fix(rivetkit-core): enumerate non-drained counters in grace deadline warn log #4746
• fix(rivetkit-core): abort graceful cleanup task when grace deadline elapses #4745 👈 (View in Graphite)
• fix(rivetkit-core): error on sleep/destroy before startup or already-requested #4743
• fix(rivetkit-core): cap SerializeState shutdown timeout at 15s #4742
• refactor(rivetkit-core): remove prevent_sleep field and deprecate set_prevent_sleep to no-op #4741
• fix(api-public): remove orphan import_export actors module #4764
• main

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

[claude]

Review: fix(rivetkit-core): abort graceful cleanup task when grace deadline elapses

The change is small and focused — adding a shutdown_deadline cancellation token that lets the NAPI receive loop race cleanup work against the grace deadline.

Correctness

The ordering in on_sleep_grace_deadline is correct:

1. Abort run_handle
2. cancel_shutdown_deadline() (new) — signals adapters to stop in-flight work
3. record_shutdown_timeout

The tokio::select! in napi_actor_events.rs correctly uses a futures-local work block so the deadline branch drops the in-progress future when it wins. reply.send(Ok(())) is called unconditionally after both branches, which is the right behavior — ActorTask needs to proceed with forced shutdown regardless of whether cleanup completed or was aborted.

Minor naming concern

cancel_shutdown_deadline reads as "cancel the deadline" (i.e., prevent it from firing), when it actually fires the signal that the deadline has elapsed. A name like fire_shutdown_deadline or signal_shutdown_deadline_elapsed would be less ambiguous. That said, the name is consistent with how CancellationToken::cancel is typically used in Tokio — cancel means "trigger" there — so it is an acceptable choice.

NAPI callback not fully cancellable

When the deadline wins the select!, the work future is dropped on the Rust side, but any ThreadsafeFunction call already in flight will still run to completion on the JS event loop. This is a fundamental NAPI limitation and not something introduced by this PR — just worth keeping in mind if onSleep/onDestroy callbacks have long-running side effects (e.g. flushing SQLite). No action needed here.

Logging

Structured fields are used correctly throughout. The ?reason debug format on StopReason will produce Sleep or Destroy, which is readable. Consistent with the existing error-path log above it.

Nit

In the new #[doc(hidden)] doc comment:

Fires when the shutdown grace deadline has elapsed and core is forcing cleanup. Foreign-runtime adapters should abort any in-flight shutdown work (for example onSleep / onDestroy) when this token is cancelled so resources like SQLite are not torn down mid-operation.

"Fires when" reads as though the token fires on its own. Consider rephrasing to "Cancelled when the shutdown grace deadline has elapsed..." to make it clear this is a CancellationToken that callers observe.

---

Overall this is clean and the approach is sound. The NAPI adapter correctly observes the deadline without any busy-waiting. No blocking issues.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4745

All packages published as 0.0.0-pr.4745.3e0079c with tag pr-4745.

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

Individual packages

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