docs: strengthen live polling URL progression invariant in SPEC.md

[KyleAMathews]

Summary

The SPEC.md loop-back URL progression invariant previously exempted live requests, treating repeated same-URL polls as "Risk: None." This was wrong — the server always advances electric-cursor on every response, so each live poll must produce a new URL. Repeated live URLs indicate broken cursor propagation and are now classified as Risk: High.

This came out of investigating a user report where an Electron app stopped receiving live updates for ~40 minutes despite the server being healthy. Clearing localStorage recovered it. We haven't pinpointed the exact failure mode yet, but tightening the spec to reflect the actual protocol contract is the right first step.

Approach

Documentation-only change. Updated the "Client Fetch Loop Paths" section of SPEC.md:

• Invariant text: Extended to cover both non-live and live requests. Added paragraph explaining cursor progression as the live-request cache-busting contract.
• L1 row: Updated "URL changes because" and "Guard" columns to distinguish catch-up (offset advances) from live (cursor advances).
• Guard mechanisms table: Added Live cursor progression as a formal guard alongside #checkFastLoop.
• Coverage gaps table: Reclassified "Live polling same URL" from Risk: None to Risk: High with updated notes.

Also added a CLAUDE.md entry requiring SPEC.md to be read before modifying the TypeScript client.

Non-goals

This PR doesn't add a client-side guard for stalled cursors — it documents that the gap exists and is high risk. A follow-up should add detection/recovery when the cursor doesn't advance (analogous to #checkFastLoop for non-live requests).

Verification

No code changes — review the diff in packages/typescript-client/SPEC.md for accuracy against the protocol.

Files changed

• CLAUDE.md — Added guidance to read SPEC.md before touching the TypeScript client
• packages/typescript-client/SPEC.md — Strengthened loop-back URL progression invariant for live polling; reclassified coverage gap risk

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.67%. Comparing base (0af96e9) to head (1935bb4).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4060   +/-   ##
=======================================
  Coverage   88.67%   88.67%           
=======================================
  Files          25       25           
  Lines        2438     2438           
  Branches      615      609    -6     
=======================================
  Hits         2162     2162           
  Misses        274      274           
  Partials        2        2           

Flag	Coverage Δ
packages/experimental	87.73% <ø> (ø)
packages/react-hooks	86.48% <ø> (ø)
packages/start	82.83% <ø> (ø)
packages/typescript-client	93.81% <ø> (ø)
packages/y-electric	56.05% <ø> (ø)
typescript	88.67% <ø> (ø)
unit-tests	88.67% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@electric-sql/react@4060

npm i https://pkg.pr.new/@electric-sql/client@4060

npm i https://pkg.pr.new/@electric-sql/y-electric@4060

commit: 1935bb4