test(rivetkit): verify cached websocket db refs exceed grace

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

• fix(pegboard): align drain grace defaults with stop threshold #4958 : 2 dependent PRs (#4960 , #4966 )
• fix(rivetkit): preserve bridge error messages #4959
• fix(rivetkit): fire abort signal on shutdown finalize #4957
• fix(rivetkit): use startup kv preload #4956
• fix(client): flatten skipReadyWait option #4955
• ci(publish): add manual preview publish flow #4954
• fix(depot): add ltx decode diagnostics #4953
• fix(universaldb): preserve plain set values #4952
• fix(universaldb): align versionstamp operand encoding #4951
• fix(rivetkit): export database provider types #4950
• wip: kitchen sink agentic loop finish #4949
• chore(rivetkit): note duplicate admission logic #4948
• test(rivetkit): cover bypass fetch header forwarding #4947
• feat(kitchen-sink): add actor probe controls #4946
• fix(gateway): split actor response wait errors #4945
• fix(guard): handle bypass preflight before query parse #4944
• feat(kitchen-sink): add mock agent event log copy #4943
• fix(kitchen-sink): default mock agent to local endpoint #4942
• test(rivetkit): enable driver lifecycle regressions #4941
• test(rivetkit): verify cached websocket db refs exceed grace #4940 👈 (View in Graphite)
• fix(rivetkit-core): keep sleeping actors reachable during grace #4939
• test(rivetkit): cover async websocket close db access #4938
• fix(rivetkit): keep actors awake until keepAwake work finishes #4937
• fix(rivetkit): persist native onSleep state on errors #4936
• fix(rivetkit-core): allow dispatch during sleep grace #4935
• fix(rivetkit): make duplicate sleep requests idempotent #4934
• main

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

[claude]

PR #4940 Review: test(rivetkit): verify cached websocket db refs exceed grace

Overview

This PR re-enables a previously skipped test (concurrent ws handlers with cached db ref get errors when grace period exceeded) that was deferred under TODO #4705. The fix is minimal: a DB write is inserted in the WebSocket handler before sending the "started" acknowledgment, making the test synchronization barrier reliable.

What the Fix Does

The race that caused the original skip:

1. The test sends 3 slow-db-work messages and waits for 3 "started" acknowledgments before triggering sleep.
2. Without this patch, a handler could send "started" immediately after capturing dbRef but before touching the DB — so sleep could begin tearing down the VFS before the handler ever made a DB call, making the "handler got an error" assertion non-deterministic.
3. With this patch, "started" is gated behind a successful dbRef.execute(...) call, so the test knows each handler has an active, in-flight DB reference before sleep is triggered.

This follows the CLAUDE.md testing guideline: root-cause the race, fix the ordering deterministically, delete the workaround note.

Code Quality

Fixture change (sleep-db.ts) — correct and minimal. The new await dbRef.execute(...) call before ws.send({ type: "started" }) is the right synchronization point.

SQL string interpolation — the new statement uses template literals with index and Date.now() directly in the SQL string, matching the existing pattern throughout the test fixtures (e.g., lines 1257-1259, 1297-1299 in the same file). Since index is always a small integer controlled by the test client and this is test-only code, there is no practical security concern.

Test change (actor-sleep-db.test.ts) — removal of test.skip and the TODO comment is clean. Test body and assertions are unchanged, which is appropriate: the fix belongs in the fixture.

Correctness

The sequencing is now:

1. Handler captures dbRef = c.db (before any await).
2. Handler does await dbRef.execute("handler-N-start") — DB is alive at this point.
3. Handler sends { type: "started" }.
4. Test accumulates 3 "started" messages, then calls actor.triggerSleep().
5. Sleep grace period (EXCEEDS_GRACE_SLEEP_TIMEOUT = 100ms) expires; VFS tears down.
6. Handlers resume after EXCEEDS_GRACE_HANDLER_DELAY + N*50ms and attempt a second dbRef.execute — gets disk I/O error or transaction error.
7. Test asserts handlerFinished < MESSAGE_COUNT.

The ordering is sound. The assertion expect(status.handlerFinished).toBeLessThan(MESSAGE_COUNT) is intentionally permissive about how many handlers slip through before VFS teardown wins, which is correct given non-deterministic timing of which handler hits the broken VFS first.

Potential Concerns

• No new vi.waitFor calls — the test already uses a waitFor helper (line 1066) predating this PR; no new polling patterns introduced.
• Timeout budget — the 15-second test timeout is generous for the 2000ms handler delay + 3x50ms stagger + 100ms sleep + 500ms buffer. No concern.
• handlerErrors assertion — expect(status.handlerErrors).toEqual([]) (line 1085) is a pre-existing invariant verifying the actor did not accumulate structured error entries, consistent with the fixture's "let it propagate" comment (DB errors are logged at the actor callback level, not surfaced as structured handlerErrors).

Summary

Clean, targeted fix. The synchronization is correct, the approach follows the codebase testing conventions, and re-enabling the skipped test is the right outcome. No blocking issues.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4940

All packages published as 0.0.0-pr.4940.3654937 with tag pr-4940.

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

Individual packages

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