fix: reconnect-path hardening (C1′ barrier, catch-up reinsert, reconnect window) — v0.3.1

[grrowl]

What & why

Three pre-existing, user-reachable bugs in the reconnect/catch-up path,
surfaced during the SSR review (PR #2 / the grill session) but independent of
SSR: they run against released @tanstack/db (>=0.6), carry no vendored
tarballs, and have tests that don't depend on the PR-1564 vendored build.
Today's non-SSR users are exposed, so these shouldn't wait for upstream to ship.

Cherry-picked from feat/ssr (d61e259, 0a378a7, 71e6bde); the third was
adapted because main has no scheduleReconnect/forced-reconnect machinery —
see below.

Fixes

1. Cursor barrier (C1′) — src/server/sync-do.ts. A snapshot's snap-end
   or a catch-up's uptodate carries the current seq, which may include changes
   whose deltas are still buffered in the coalescer for that socket. The client's
   single cursor then claims a seq it never applied; a drop before the tick loses
   the write permanently (reconnect resumes past it). The server now flushes the
   socket's pending deltas before any cursor-advancing emission. Reachable on any
   multi-collection reconnect. Generalizes ADR-0002 C1 from committed to all
   cursor boundaries.

2. Held-key catch-up reinsert — src/client/do-collection.ts. A catch-up
   emits the latest CDC op per key, so a key deleted-and-reinserted while the
   client was away arrives as insert for a key the client still holds.
   TanStack throws DuplicateKeySyncError on insert-over-existing, aborting the
   whole catch-up transaction and wedging the client on stale state. The adapter
   now applies a held-key insert as the upsert it semantically is (the move-in
   update-upsert contract, ADR-0002 C4).

3. Reconnect window — src/client/transport.ts. The reconnecting flag was
   set inside the reconnect timer, so a mutation fired within reconnectDelayMs
   of a drop established the fresh socket before the timer ran — with no
   resubscribe, leaving every subscription silently dead on the new socket (and
   the late timer wedged the flag). The flag is now set when the reconnect is
   scheduled, so whichever connect wins — timer- or demand-driven — resubscribes
   from the cursor.

Adaptation note (fix 3)

main has no scheduleReconnect()/forceReconnect()/suppressAdvance (those
are SSR-only). The fix here is the equivalent one-line hoist in the close
handler's inline reconnect timer. The suppressAdvance half of the original
race (a frozen cursor on the forced-reconnect path) does not exist on main, so
this commit carries only the close-handler hoist, and the test's WHY drops that
sentence. Reviewed adversarially with codex --model gpt-5.5: hoisting is
correct given connect() is idempotent and demand-callable; no new race.

ADR-0011 references

ADR-0011 (SSR design) is unmerged. CHANGELOG entries are self-contained — no
ADR-0011 reference. Code/test comments keep it as provenance (the fixes
genuinely originated there); those resolve once feat/ssr lands.

Verification

• npm run typecheck — clean.
• npm run test — 143 passed (36 files), including the three new tests
  (cursor-barrier, reinsert-catchup, reconnect-window), each of which
  fails without its fix.

Release

Includes chore(release): v0.3.1 (CHANGELOG [0.3.1] + package.json bump),
mirroring the 0.3.0 release commit. The v0.3.1 git tag and npm publish are
intentionally left for @grrowl to run (authed publish).

🤖 Generated with Claude Code