test(client): add fast-check model-based property tests and retry bound analysis

[KyleAMathews]

Summary

Fixes four bugs in ShapeStream's retry and error-handling paths, found via model-based property testing and static analysis. The bugs could cause infinite retry loops, stale data delivery to subscribers, stack frame leaks, and cache key divergence.

Root Cause

All four bugs share a pattern: they're edge cases in error-handling paths that only manifest under specific sequences of server responses. Hand-written tests don't naturally explore adversarial sequences like "409 with same handle, then 409 with no handle, then 200 with empty body." These bugs survived because they required rare combinations — a 409 where the proxy strips the handle header, or a deprecated query param that nobody adds to the protocol list.

Approach

Two complementary verification strategies that catch bugs mechanically:

Model-based property testing (fast-check)

fc.asyncModelRun with 8 command types generates adversarial server response sequences. A simple model tracks { consecutiveErrors, terminated }, and each command predicts the model's state change before asserting the real ShapeStream matches.

FetchGate pattern: A controllable mock fetch that blocks each request until the test provides a response — turn-based coordination where the test controls what the server returns while ShapeStream drives when it fetches.

Global invariants checked after every command:

• URL length stays bounded (catches suffix growth)
• isUpToDate / lastSyncedAt consistency
• After 409, the retry URL differs from the pre-409 URL (catches identity loops)

Static analysis via AST walking

Seven rule types that mechanically detect structural bug patterns:

Rule	What it catches
unbounded-retry-loop	Recursive calls in catch blocks without detectable bounds
conditional-409-cache-buster	409 handlers where createCacheBuster() is conditional or missing
parked-tail-await	await this.#method(); return patterns that park stack frames
error-path-publish	#publish/#onMessages calls inside catch blocks or error status handlers
shared-instance-field	Mutable fields written before async boundaries and read by other methods
ignored-response-transition	Non-delegate states returning { action: 'ignored' }
protocol-literal-drift	Near-miss string literals for Electric protocol params

Each rule was RED/GREEN verified: temporarily reintroduce the bug → rule fires; revert → rule passes clean.

Bugs Fixed

Bug 1: Conditional cache buster on 409

When the server returned a 409 with the same handle (or no handle), createCacheBuster() was only called in the no-handle branch. Same-handle 409s produced identical retry URLs, causing infinite CDN-cached retry loops.

Fix: createCacheBuster() is now unconditional on every 409 — both in #requestShape and #fetchSnapshotWithRetry.

Bug 2: Parked stack frame in #start retry

await this.#start(); return kept the caller's frame alive for the entire recursive chain. Under repeated error-recovery cycles, this accumulated O(n) suspended frames.

Fix: return this.#start() releases the frame via promise chaining.

Bug 3: Missing EXPERIMENTAL_LIVE_SSE_QUERY_PARAM in protocol params

The deprecated experimental_live_sse param wasn't in ELECTRIC_PROTOCOL_QUERY_PARAMS, so canonicalShapeKey wouldn't strip it. Clients using the deprecated param would get different cache keys from clients using the current live_sse param.

Fix: Added to the array. Static analysis test now verifies all internal *_QUERY_PARAM exports are in the list.

Bug 4: Publishing 409 body to subscribers

The 409 handler parsed e.json and called await this.#publish(messages409) before retrying. This delivered stale/partial rotation messages to subscribers, which could corrupt client-side state.

Fix: Removed the publish call entirely. 409 is a control-plane signal — the retry will deliver fresh data from offset -1.

Key Invariants

1. Every 409 handler unconditionally calls createCacheBuster() before retrying
2. Every recursive call in a catch block has a detectable retry bound (counter, type-guard, abort-signal, or callback-gate)
3. No await this.#method(); return in recursive methods (use return this.#method() instead)
4. No #publish or #onMessages calls in error handling paths
5. All internal *_QUERY_PARAM constants appear in ELECTRIC_PROTOCOL_QUERY_PARAMS
6. Consecutive error counter resets only on proven success (200 with data, 200 up-to-date, 204)

Non-goals

• Refactoring #start/#requestShape into iterative loops (structural change, separate PR)
• Fixing the pgArrayParser double-push bug (pre-existing, unreachable for valid PostgreSQL arrays)
• Testing network-level failures or backoff timing (model tests focus on response sequences)
• The wake detection queueMicrotask timing issue (pre-existing, requires deeper investigation)

Verification

cd packages/typescript-client
pnpm vitest run --config vitest.unit.config.ts

Files changed

File	Change
src/client.ts	Unconditional cache buster on 409 (both handlers), return this.#start() instead of await, removed #publish from 409 handler, updated 409 comment
src/constants.ts	Added EXPERIMENTAL_LIVE_SSE_QUERY_PARAM to ELECTRIC_PROTOCOL_QUERY_PARAMS
test/model-based.test.ts	New: 8 response factories, FetchGate class, 8 command classes, model definition, global invariant assertions
test/static-analysis.test.ts	Tests for all 7 static analysis rules including protocol param completeness
bin/lib/shape-stream-static-analysis.mjs	AST-based analysis: unbounded retry, 409 cache buster, tail-position await, error-path publish, protocol literal drift
SPEC.md	Updated loop-back site line numbers (L1-L6) after code changes
vitest.unit.config.ts	Added model-based test to include list
package.json	Added fast-check devDependency

---

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

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

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

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

commit: fafcd59

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.84%. Comparing base (c740930) to head (fafcd59).
⚠️ Report is 2 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4089      +/-   ##
==========================================
+ Coverage   88.67%   88.84%   +0.16%     
==========================================
  Files          25       25              
  Lines        2438     2430       -8     
  Branches      615      604      -11     
==========================================
- Hits         2162     2159       -3     
+ Misses        274      269       -5     
  Partials        2        2              

Flag	Coverage Δ
packages/experimental	87.73% <ø> (ø)
packages/react-hooks	86.48% <ø> (ø)
packages/start	82.83% <ø> (ø)
packages/typescript-client	94.07% <100.00%> (+0.25%)	⬆️
packages/y-electric	56.05% <ø> (ø)
typescript	88.84% <100.00%> (+0.16%)	⬆️
unit-tests	88.84% <100.00%> (+0.16%)	⬆️

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.