refactor(rivetkit-core): rename StopReason to ShutdownKind and kill enum fallthroughs

[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]

• chore(kitchen-sink): configurable endpoint #4766 : 3 dependent PRs (#4754 , #4777 , #4778 )
• refactor(rivetkit-core): rename StopReason to ShutdownKind and kill enum fallthroughs #4765 👈 (View in Graphite)
• 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
• 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: refactor(rivetkit-core): rename StopReason to ShutdownKind and kill enum fallthroughs

Overall this is a clean, well-executed refactor that also ships a meaningful bug fix. A few notes below.

---

Rename is semantically clearer. ShutdownKind communicates what type of shutdown (Sleep vs Destroy) rather than the vague StopReason which sounds more like an error description. Naming is a real improvement.

New map_envoy_stop_reason helper is the right call. Centralizing the protocol->lifecycle mapping into one explicit function makes the semantics visible and testable. The inline comments on each arm explaining the why (reallocation, connection loss, etc.) add genuine value.

LifecycleCommand::stop_reason fallthrough removal (line 184) is exactly the kind of change the new CLAUDE.md rule is driving: adding Start and FireAlarm arms explicitly instead of _ => None means future LifecycleCommand variants will be a compile error rather than a silent behavior change.

*RegistryState exhaustive match in registry.rs line 950 follows the same pattern correctly.

---

Behavioral change worth calling out explicitly

The most significant part of this PR is not the rename. It is the semantic correction for GoingAway and Lost in map_envoy_stop_reason:

Before (via the _ => StopReason::Destroy fallthrough):

• GoingAway => Destroy — actor's onDestroy fires incorrectly on drain/reallocation
• Lost => Destroy — actor's onDestroy fires on runner reconnect

After (explicit):

• GoingAway => Sleep — runner drained; engine reallocates; state preserved
• FLost => Sleep` — connection lost; actor resurrects with same id

This is a real bug fix. Actors were previously receiving an onDestroy callback and having their durable state wiped on runner drains and lost connections. That should be called out in the PR description rather than being buried in a refactor.

---

Minor notes

Double mark_destroy_requested call sites. Both call sites in registry/mod.rs (lines ~418 and ~432) now call map_envoy_stop_reason independently. This is correct and consistent.

map_envoy_stop_reason takes &StopActorReason. If the type is Copy (common for protocol enums), taking by value would be the conventional Rust style. Not a bug, just a minor style note.

Comment on LifecycleState fallthrough removal explains the intent well. Minor CLAUDE.md alignment: "Pre-startup, post-finalize, and tear-down states intentionally drop activity signals: there is no sleep deadline to reset and no grace window left to advance." The dash-separated list at the start is slightly fragmented. Could tighten to: "Loading, finalize, and terminated states have no active sleep deadline or grace window, so activity signals are dropped." Not blocking.

---

The main ask is to update the PR description to surface the GoingAway/Lost behavioral fix. It is the most impactful change and reviewers should not have to deduce it from the fallthrough elimination.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4765

All packages published as 0.0.0-pr.4765.cf49dd6 with tag pr-4765.

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

Individual packages

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