docs: add keepAwake vs waitUntil table and internal sleep-sequence invariants

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

PR #4749 Review: keepAwake / waitUntil docs and sleep-sequence invariants

This is a documentation-only PR that introduces user-facing keepAwake/waitUntil docs, replaces the deprecated setPreventSleep API in the public lifecycle page, adds the internal reference doc docs-internal/engine/sleep-sequence.md, and updates CLAUDE.md entries. Content accuracy looks good overall, but several issues remain unresolved.

---

Issues

1. Em dashes in sleep-sequence.md — must fix (CLAUDE.md convention)

CLAUDE.md: "Do not use em dashes (—). Use periods to separate sentences instead."

Lines 33–34 of docs-internal/engine/sleep-sequence.md:

- `can_arm_sleep_timer()` — the idle predicate. Returns ...
- `can_finalize_sleep()` — the grace predicate. Returns ...

Suggested fix:

- `can_arm_sleep_timer()` is the idle predicate. Returns ...
- `can_finalize_sleep()` is the grace predicate. Returns ...

2. Verbose implementation-wiring bullet in rivetkit-rust/packages/rivetkit-core/CLAUDE.md

The CLAUDE.md meta-rule says: "keep entries concise, ideally a single bullet... do not add current implementation wiring." The added bullet names specific function symbols (on_sleep_grace_deadline, shutdown_deadline_token()) and mandates a specific Rust primitive (tokio::select!). That implementation wiring belongs in docs-internal/engine/sleep-sequence.md (where it already appears in full), not in CLAUDE.md. Suggest condensing to:

Foreign-runtime adapters running onSleep/onDestroy must observe the grace deadline token so SQLite teardown does not race user cleanup work.

3. Prose/table mismatch for "disconnects" in lifecycle.mdx

The prose paragraph at line 830 lists the grace window contents as:

hooks, waitUntil, keepAwake, async raw WebSocket handlers such as message and close

The table description directly below at line 837 includes "disconnects" as well. The prose should be brought into alignment by appending "and disconnect callbacks."

---

Additional observations (non-blocking)

4. "Will be removed in 2.2.0" claim is stale

docs-internal/engine/sleep-sequence.md states setPreventSleep will be removed in 2.2.0. The package is currently at 2.3.0-rc.4, so 2.2.0 has already shipped. The removal target version should be updated or reworded to "will be removed in a future release."

5. Stale preventSleep references in other docs pages (pre-existing, touched area)

limits.mdx:131, versions.mdx:360, and general/architecture.mdx:75 still describe setPreventSleep/preventSleep as the active keep-awake primitive. Since this PR is the canonical migration point, these are natural follow-up items. The .claude/reference/docs-sync.md table should list them.

6. agent-os/actor/index.ts still calls c.setPreventSleep (pre-existing)

rivetkit-typescript/packages/rivetkit/src/agent-os/actor/index.ts:108 calls c.setPreventSleep(shouldPrevent). Since setPreventSleep is now a no-op, syncPreventSleep no longer actually prevents sleep. Worth tracking as a follow-up given this PR declares the deprecation complete.

7. noSleep deprecation JSDoc still references setPreventSleep (pre-existing)

config.ts:887: @deprecated Use c.setPreventSleep(true) for bounded delays.... This deprecation comment now directs users to another deprecated API.

8. workflow/context.ts waitUntil JSDoc references setPreventSleep (pre-existing)

workflow/context.ts:548–550 says "or c.setPreventSleep(true) while work is active" — stale now that setPreventSleep is a no-op.

---

What looks correct

• The keepAwake vs waitUntil comparison table is accurate and matches the can_arm_sleep_timer / can_finalize_sleep semantics described in sleep-sequence.md.
• The declare function processTurn stub makes the new code block self-contained for the website typecheck pass.
• Placement of sleep-sequence.md in docs-internal/engine/ is correct per CLAUDE.md conventions.
• The Rust test file (rivetkit-core/tests/modules/sleep.rs) and TypeScript test files (actor-sleep.test.ts, actor-sleep-db.test.ts) referenced in the "Test harness parity" section all exist.
• The CLAUDE.md root entry linking sleep-sequence.md is appropriately one-line.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4749

All packages published as 0.0.0-pr.4749.b8e0e45 with tag pr-4749.

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

Individual packages

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