fix(envoy-client): dedupe replayed commands by index

[NathanFlurry]

Stack Context

Builds on #4801 (engine-stabilize/envoy-client-lifecycle), which already added
an immediate send_command_ack after every handle_commands batch. This PR
closes the residual race where a command arrives, is processed, but the ack
frame doesn't reach the engine before the WS drops — on reconnect,
pegboard-envoy re-streams the same command from UDB and the envoy processes
it twice.

Why?

EnvoyContext::handle_commands had no dedup on the receive path. Two concrete
bugs:

1. Replayed CommandStartActor clobbered live actors. insert_actor
   unconditionally re-inserts into ctx.actors[actor_id][generation],
   dropping the existing handle, event_history, and active_http_request_count
   on the floor. The spawned actor task was orphaned.
2. Replayed CommandStopActor re-fired ToActor::Stop. Idempotent in
   best case, double-shutdown signal in worst case.

ActorEntry::last_command_idx already existed but was only read by
send_command_ack — never checked against incoming command indices.

What?

• EnvoyContext gains processed_command_idx: HashMap<(String, u32), i64>.
  Persists across remove_actor so a replayed start for an
  already-stopped actor cannot resurrect it.
• handle_commands skips any command whose checkpoint.index <= last_processed
  for the (actor_id, generation) pair, then records the new index before
  dispatching.
• New integration test under tests/command_dedup.rs covers same-index replay,
  stale lower-index replay, monotonic processing, and per-actor / per-generation
  isolation. Lives in tests/ rather than inline #[cfg(test)] mod tests
  because a pre-existing 7-vs-8 arg mismatch in actor.rs test code blocks the
  lib-test target on this branch — the integration test target compiles
  independently.

Test plan

• cargo check -p rivet-envoy-client
• cargo test -p rivet-envoy-client --test command_dedup (2 passed)

[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

• fix(envoy-client): dedupe replayed commands by index #4811 : 2 dependent PRs (#4802 , #4812 ) 👈 (View in Graphite)
• fix(envoy-client): complete command and request lifecycles #4801
• fix(guard): serialize gateway actor keys correctly #4655 : 1 other dependent PR (#4800 )
• chore(rivetkit): remove inline tests #4668 : 1 other dependent PR (#4657 )
• fix(api): subscribe before namespace workflow dispatch #4654
• fix(rivetkit): restore hibernatable sockets and hydrate serverless starts #4658
• test(rivetkit): stabilize actor db driver tests #4664 : 1 other dependent PR (#4656 )
• fix(test): stabilize lifecycle, sleep, queue, and run edge cases #4660 : 1 other dependent PR (#4665 )
• test(rivetkit): re-enable gateway URL and direct-registry coverage #4659
• fix(rivetkit): keep internal error exposure behavior consistent #4661
• fix(rivetkit): add lifecycle error retry and gateway HTTP routing #4666
• fix(rivetkit-core): remove legacy timeouts #4799
• chore: add CLAUDE.md guidance on test fixtures, SDK regen, and TS client layer #4796
• fix(inspector): stream patched state updates #4795
• fix(rivetkit): refresh stale actor handles #4794
• test(rivetkit-napi): move private tests to crate root #4793
• test(rivetkit-core): move private tests to crate root #4792
• test(runner-configs): assert envoy protocol version #4791
• fix(serverless): split metadata protocol errors #4789 : 1 other dependent PR (#4790 )
• chore(sqlite): add open close lifecycle for envoy actors #4788
• fix(rivetkit): share lifecycle shutdown grace #4810
• fix(pegboard): move sqlite v1 migration into actor workflow #4787 : 1 other dependent PR (#4797 )
• test(rivetkit): cover c.db access from onWake/onSleep/onDestroy #4786
• fix(rivetkit-napi): run onMigrate before createState/onCreate/createVars #4785
• refactor(rivetkit-core): merge ready+started into lifecycle_started, drop redundant napi calls #4784
• fix(rivetkit): drain native sleep side tasks reliably #4782 : 1 other dependent PR (#4783 )
• fix(rivetkit): route raw request fetches to actors #4781
• fix(pegboard): refresh runner config after envoy connect #4778 : 2 other dependent PRs (#4779 , #4798 )
• chore(kitchen-sink): configurable endpoint #4766 : 2 other dependent PRs (#4754 , #4777 )
• 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
• 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: fix(envoy-client): dedupe replayed commands by index

Overall: The fix is correct and well-targeted. The two concrete bugs (replayed CommandStartActor clobbering live actors, replayed CommandStopActor re-firing ToActor::Stop) were real. A context-level dedup map that survives remove_actor is the right design. A few issues are worth addressing before merging.

---

Issues

1. Stopped actors are never acked after removal

send_command_ack iterates only ctx.actors, so once an actor is removed via remove_actor, its final command index is never acked to the engine. With processed_command_idx intentionally surviving removal, the engine will keep replaying the stop command on every reconnect — the dedup silences the double-dispatch locally, but the engine's replay loop stays open indefinitely.

Concretely: a CommandStopActor at index 5 is processed, processed_command_idx[("a", 1)] = 5 is set, remove_actor cleans up ctx.actors["a"], but send_command_ack never emits a checkpoint for ("a", 1). On reconnect the engine re-sends index 5, the dedup drops it — but the cycle repeats forever.

Fix: After the ctx.actors loop in send_command_ack, also emit checkpoints for entries in processed_command_idx that aren't already covered by a live actor.

2. Two parallel tracking mechanisms can diverge

ActorEntry::last_command_idx and ctx.processed_command_idx are now both updated for commands but independently. last_command_idx is pruned when an actor is removed; processed_command_idx persists. The two mechanisms serve different roles (ack source vs. replay filter), but without a comment this distinction is invisible and will invite future drift. A brief comment clarifying which is the ack source and which is the replay filter would reduce confusion.

3. Missing test: CommandStartActor replay

The PR description identifies replayed CommandStartActor as the primary bug, but command_dedup.rs only adds tests for CommandStopActor. A test asserting that a replayed start command does not re-create the actor would directly cover bug #1 and prevent regression. Currently the critical path has no automated coverage.

4. Unbounded map growth

processed_command_idx is never pruned — one entry per (actor_id, generation) pair ever seen. In practice this is bounded by the total actors ever hosted per envoy process, but a comment noting this assumption (or a size cap for long-lived envoys cycling through many actors) would be prudent.

---

Minor

• tracing::debug! uses actor_id = %checkpoint.actor_id (Display) but last_idx as a bare positional value. Per CLAUDE.md conventions, prefer named structured fields: last_idx = last_idx or ?last_idx.

• std::collections::HashMap in EnvoyContext is correct here — EnvoyContext is owned exclusively by the single envoy_loop task, so the scc::HashMap rule (for shared concurrent maps) does not apply.

• Tests correctly live under tests/ rather than inline #[cfg(test)], matching CLAUDE.md conventions.

• The pre-existing 7-vs-8 arg mismatch in actor.rs test code noted in the PR description should be tracked as a follow-up to keep the test surface coherent after this lands.

[NathanFlurry]

Landed in main via stack-merge fast-forward push. Commits are in main; closing to match.

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4811

All packages published as 0.0.0-pr.4811.6b7e318 with tag pr-4811.

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

Individual packages

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

[github-actions]

Preview packages published to npm

Install with:

npm install rivetkit@pr-4811

All packages published as 0.0.0-pr.4811.6b7e318 with tag pr-4811.

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

Individual packages

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