docs(rivetkit): document keepAwake/waitUntil counter-arm race and surface bridge errors

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

PR Review: docs(rivetkit): document keepAwake/waitUntil counter-arm race and surface bridge errors

Overall: Good improvement — tightens error handling and documents a subtle timing invariant that would otherwise be easy to misread as a bug.

---

Strengths

• Documentation quality: The counter-arm race comment is precise. It names the race, explains why it is safe (sleep timer debounce), and states the accepted trade-off. Developers reading this won't chase a phantom bug.
• Error handling: Replacing bare void callNative(...) with .catch() is correct. Unhandled rejections on fire-and-forget calls can surface as noisy warnings in Node and now they're handled explicitly.
• Consistent pattern: Both keepAwake and waitUntil follow identical error handling logic, which is good for maintainability.
• Expected error filtering: Silencing isClosedTaskRegistrationError for shutdown-path noise is the right call per CLAUDE.md conventions (expected teardown errors should not clutter warnings).

---

Issues

Minor: Comment style does not follow CLAUDE.md conventions

CLAUDE.md specifies: write comments as normal, complete sentences and avoid fragmented structures with parentheticals and dashes.

The keepAwake comment uses parenthetical annotations like (acceptable) and (default 30s), and semicolons as sentence separators. These should be normal complete sentences. Not a blocker but worth tidying before merge.

Minor: waitUntil comment references keepAwake for full context

The waitUntil comment is terser and says "same counter-arm race as keepAwake". A reader must context-switch between methods to understand either. Consider making each comment self-contained, or placing a single shared explanation above both methods.

Cosmetic: void removal is intentional but undocumented

In keepAwake, the original void callNative(...) loses its void. This is correct (the .catch() now handles the rejection), but a reviewer might flag it as accidental. No action needed, just noting it is deliberate.

---

Test Coverage

Existing driver tests in actor-sleep-db.test.ts cover the waitUntil happy path and rejection-during-shutdown scenarios. No new tests are strictly required for this documentation and error-logging change. However, these paths are currently untested:

• Warn log fires when callNative rejects with a non-shutdown error.
• isClosedTaskRegistrationError errors are silently swallowed with no spurious warnings during shutdown.

Low priority given the code paths are simple, but worth a follow-up to guard against future regression.

---

Summary

Correct and safe. Two minor points worth addressing before merge: comment style per CLAUDE.md, and optionally making the waitUntil comment self-contained. No blocking issues.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4759

All packages published as 0.0.0-pr.4759.2611022 with tag pr-4759.

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

Individual packages

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