Implement incremental catch-up and heartbeat for sync resilience

[noahm]

Summary

This PR implements two critical improvements to the PartyKit sync protocol to make brief network disruptions nearly free and detect stalled connections:

1. Incremental catch-up: When a client detects a gap in action sequence numbers on a live socket, it now asks the server to replay just the missing actions instead of forcing a full reconnect. The server maintains an in-memory tail of recent stamped actions and responds with the gap-filling actions, or falls back to a full roomstate if the gap predates the retained tail.

2. Application-level heartbeat: Clients now ping the server every ~10 seconds and treat 2 unanswered pings as a dead connection, forcing a reconnect. This surfaces stalled-but-open sockets (e.g., frozen server, half-open TCP) that would otherwise go unnoticed until an ack timeout.

3. Persistent sequencer metadata: The server now persists seq and the dedupe id set to room storage (syncMeta key) so hibernation/restarts don't reset the sequencer or forget applied ids, closing a small dedupe window.

Key Changes

Client (src/party/sync-manager.ts):

• Added resyncing flag and buffer array to hold live broadcasts while a catch-up repair is in flight
• New handleCatchup() method to apply replayed stamped actions and drain buffered broadcasts
• New ingest() method extracted from handleRemoteAction() to apply a single action with gap detection
• On gap detection, calls requestCatchup(since) instead of immediately calling resync()
• Catch-up requests retry on 5s timeout with MAX_CATCHUP_ATTEMPTS (3) before falling back to full reconnect
• Added dispose() to clean up timers and buffers

Server (src/party/server.ts):

• Added in-memory tail array storing the last 500 stamped actions for catch-up replies
• New handleCatchup() method that returns missing actions from the tail or a full roomstate if the gap is too old
• Persists seq and seenIds to room storage under SYNC_META_KEY on startup and after each action
• Refactored onMessage() to dispatch by message type (action, catchup, ping)
• rememberActionId() renamed to rememberStampedAction() and now maintains the tail

Client socket manager (src/party/client.tsx):

• Added heartbeat loop that pings every HEARTBEAT_INTERVAL_MS (10s)
• Tracks missedPongsRef and forces reconnect after MAX_MISSED_PONGS (2) unanswered pings
• Pong counter resets on any pong or fresh roomstate arrival
• Wired requestCatchup() handler to send catchup messages

Protocol types (src/party/types.ts):

• New StampedAction type: a ReduxAction with guaranteed id and seq
• New CatchupRequest and CatchupResponse message types
• New Ping and Pong message types
• Updated ClientMessage and Broadcast union types

Documentation (docs/partykit-sync-design.md and docs/partykit-sync-roadmap.md):

• Documented the catch-up flow, including buffer/drain mechanics and fallback to reconnect
• Explained why the tail is memory-only (safe because clients only catch up on live sockets)
• Documented the heartbeat mechanism and the stalled-socket failure mode it addresses
• Updated version interop notes: older servers ignore catchup/ping and degrade gracefully

Notable Implementation Details

• Buffer and drain: While a catch-up is in flight, live broadcasts are buffered and replayed in seq order once the gap closes. If a gap reopens mid-drain, another catch-up round begins.
• Memory-only tail: The tail is deliberately not persisted to room storage. A client can only observe a live-socket gap while the same actor has been running

https://claude.ai/code/session_01Tuc1MxeNwT1rU9bxSuVMUX

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ddr-tools	Ready	Preview	Jul 8, 2026 11:18pm