refactor(rivetkit): deprecate setPreventSleep to no-op in TypeScript

[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 👈 (View in Graphite)
• 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]

PR Review: refactor(rivetkit): deprecate setPreventSleep to no-op in TypeScript

Overview

This PR deprecates the boolean setPreventSleep / preventSleep API in favor of the promise-based keepAwake(promise) and waitUntil(promise) pattern. The native adapter and workflow context both stub out the old API as no-ops. The approach is sound — promise-based lifecycle tracking is cleaner and avoids the misuse patterns that the boolean flag enabled.

---

Issues

Behavioral change with no-op preventSleep getter (minor risk)

The getter preventSleep now always returns false instead of the actual tracked value. Any consumer that reads this value to make a decision (e.g., if (ctx.preventSleep) { ... }) will now silently see false even if sleep was logically blocked. This is a correct deprecation but is a subtle semantic break rather than a pure no-op. Worth calling out explicitly in the deprecation notice or changelog.

workflow/context.ts setter still calls #ensureActorAccess (minor inconsistency)

setPreventSleep(_prevent: boolean): void {
    this.#ensureActorAccess("setPreventSleep");  // still throws if called outside valid context
}

The setter is described as a no-op, but it still throws if called from an invalid context. This is inconsistent with the native.ts adapter where the stub is a pure no-op with no access check. The behavior should be consistent or the inconsistency documented.

TODO comment wording (instance/mod.ts)

// TODO(sleep-cleanup): investigate whether ActorInstance / drivers/engine
// path is still needed after native path maturation. preventSleep tracking
// below is retained for legacy driver compatibility but no longer drives core.

Per CLAUDE.md conventions, comments should not document deltas ("retained for legacy driver compatibility") since that context rots quickly. Consider trimming to just "preventSleep tracking is a legacy driver compatibility shim" and moving the investigation note to .agent/todo/.

No tests added

The PR checklist items for tests are unchecked. Since preventSleep now always returns false and setPreventSleep is a no-op, a regression could silently reintroduce the native call. A simple test asserting ctx.preventSleep === false and that setPreventSleep does not throw would provide a safety net.

Removal version consistency

Both @deprecated notices say "Will be removed in 2.2.0". Confirm this matches the actual release plan — if the version target changes, both spots will need updating.

---

Suggestions

• Consider checking whether setPreventSleep appears anywhere in docs/guides and updating those callsites.
• The keepAwake JSDoc update (removing the old @deprecated pointing back to setPreventSleep) is correct and well-done.

---

Summary

The direction is correct — promise-scoped lifecycle tracking is a better API. The main risk is the preventSleep getter silently returning false for any code that was reading it. The no-test concern and TODO comment wording are minor. The #ensureActorAccess inconsistency between workflow/context.ts and native.ts is worth resolving for consistency.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4747

All packages published as 0.0.0-pr.4747.3298821 with tag pr-4747.

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

Individual packages

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