Realtime: stop rows popping out and back in

[HomemadeToast57]

The bug

Add several todos quickly and some vanish for a moment, then come back. Measured on a live app — a row the user had already added was absent from the screen for 200ms:

351ms  n=4  [rapid-3, rapid-2, rapid-1, wire-test-A]   all visible
451ms  n=3  [rapid-2, rapid-1, wire-test-A]            rapid-3 VANISHES
651ms  n=4  [rapid-3, rapid-2, rapid-1, wire-test-A]   back, 200ms later

It's a lost-update race, not latency. The doorbell says "something changed" without saying which row, so the app reloads its whole list on every ping. A reload issued while the app's own inserts are still in flight comes back without them, and replaces what's on screen with a snapshot missing rows the user already added.

An instantaneous network wouldn't help — the snapshot legitimately lacks uncommitted rows. Speed cannot fix this.

The fix

The SDK is the one place that sees both sides of the race: it issues every write and owns the broadcast handler. So it withholds the reload signal while this client's writes are landing, and fires once when they drain.

Your three-add case now resolves as: three writes in flight → every ping held → last write settles → one reload, which returns [A,B,C] and matches what's already on screen. Nothing moves.

Plus a short trailing coalesce, since the trigger fires per changed row — a bulk write produces N pings for one logical refresh. And a ceiling on the hold, so continuous local editing can't starve the app of other users' changes.

Why this approach

Three ways to fix this were on the table. This one was chosen because it's the only one that fixes apps that already exist.

	needs new app code?	reaches existing apps?
this — hold the reload	no	yes, on next publish
id in payload + merge-by-id	yes	no
live-list store / hook	yes	no

No new API, no prompt rewrite, no server change, no version gating. Existing apps running subscribe(() => load()) simply stop flickering when they next publish.

What it does NOT fix

A ping still triggers a full table reload — just never a racing one. The wasted bandwidth is untouched, and that's what the id-in-payload and live-store work address. Those stay worth doing; they're tracked separately and are additive to this.

Implementation note

Writes are counted in proxyFetch, not in the entities layer, because both styles we teach — supabase.from(...).insert(...) and bool.entities.x.create(...) — funnel through that fetch and only one goes via entities. There's a test for the raw-supabase path specifically.

Tests

9 new tests that make the race deterministic: writes park until the test releases them, so "in flight" is decided rather than timed. Covers the three-rapid-writes case, burst coalescing, a failed write not leaking the counter, reads never holding anything back, unsubscribe cancelling a pending reload, and the raw-supabase write path.

117 pass, typecheck clean.

🤖 Generated with Claude Code