fix(client): add EXPERIMENTAL_LIVE_SSE_QUERY_PARAM to protocol params list

The deprecated `experimental_live_sse` query param was missing from
ELECTRIC_PROTOCOL_QUERY_PARAMS, causing canonicalShapeKey to produce
different keys for the same shape depending on whether the SSE code
path added the param to the URL. This caused:

- expiredShapesCache entries written during SSE to be invisible when
  the stream fell back to long polling
- upToDateTracker entries from SSE sessions to be lost on page refresh
- fast-loop cache clearing to target the wrong key during SSE

Also adds a static analysis test that verifies all internal protocol
query param constants are included in the protocol params list, and
updates SPEC.md with the unconditional 409 cache buster invariant.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: KyleAMathews

packages/typescript-client/SPEC.md

@@ -342,26 +342,38 @@ change the next request URL via state advancement or an explicit cache buster.
 This is enforced by the path-specific guards listed below. Live requests
 (`live=true`) legitimately reuse URLs.
 
+### Invariant: unconditional 409 cache buster
+
+Every code path that handles a 409 response must unconditionally call
+`createCacheBuster()` before retrying. This ensures unique retry URLs regardless
+of whether the server returns a new handle, the same handle, or no handle. The
+cache buster is stripped by `canonicalShapeKey` so it doesn't affect shape
+identity or caching logic — it only affects the raw URL sent to the server/CDN.
+
+**Enforcement**: Static analysis rule `conditional-409-cache-buster` in
+`shape-stream-static-analysis.mjs` + model-based property test commands
+`Respond409SameHandleCmd` and `Respond409NoHandleCmd`.
+
 ### Loop-back sites
 
 Six sites in `client.ts` recurse or loop to issue a new fetch:
 
-| #   | Site                                    | Line | Trigger                                                    | URL changes because                                                                 | Guard                                                   |
-| --- | --------------------------------------- | ---- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------- |
-| L1  | `#requestShape` → `#requestShape`       | 940  | Normal completion after `#fetchShape()`                    | Offset advances from response headers                                               | `#checkFastLoop` (non-live)                             |
-| L2  | `#requestShape` catch → `#requestShape` | 874  | Abort with `FORCE_DISCONNECT_AND_REFRESH` or `SYSTEM_WAKE` | `isRefreshing` flag changes `canLongPoll`, affecting `live` param                   | Abort signals are discrete events                       |
-| L3  | `#requestShape` catch → `#requestShape` | 886  | `StaleCacheError` thrown by `#onInitialResponse`           | `StaleRetryState` adds `cache_buster` param                                         | `maxStaleCacheRetries` counter in state machine         |
-| L4  | `#requestShape` catch → `#requestShape` | 924  | HTTP 409 (shape rotation)                                  | `#reset()` sets offset=-1 + new handle; or request-scoped cache buster if no handle | New handle from 409 response or unique retry URL        |
-| L5  | `#start` catch → `#start`               | 782  | Exception + `onError` returns retry opts                   | Params/headers merged from `retryOpts`                                              | User-controlled; `#checkFastLoop` on next iteration     |
-| L6  | `fetchSnapshot` catch → `fetchSnapshot` | 1975 | HTTP 409 on snapshot fetch                                 | New handle via `withHandle()`; or local retry cache buster if same/no handle        | `#maxSnapshotRetries` (5) + cache buster on same handle |
+| #   | Site                                    | Line | Trigger                                                    | URL changes because                                                             | Guard                                                  |
+| --- | --------------------------------------- | ---- | ---------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| L1  | `#requestShape` → `#requestShape`       | 940  | Normal completion after `#fetchShape()`                    | Offset advances from response headers                                           | `#checkFastLoop` (non-live)                            |
+| L2  | `#requestShape` catch → `#requestShape` | 874  | Abort with `FORCE_DISCONNECT_AND_REFRESH` or `SYSTEM_WAKE` | `isRefreshing` flag changes `canLongPoll`, affecting `live` param               | Abort signals are discrete events                      |
+| L3  | `#requestShape` catch → `#requestShape` | 886  | `StaleCacheError` thrown by `#onInitialResponse`           | `StaleRetryState` adds `cache_buster` param                                     | `maxStaleCacheRetries` counter in state machine        |
+| L4  | `#requestShape` catch → `#requestShape` | 924  | HTTP 409 (shape rotation)                                  | `#reset()` sets offset=-1 + new handle; unconditional cache buster on every 409 | New handle + unique retry URL via cache buster         |
+| L5  | `#start` catch → `#start`               | 782  | Exception + `onError` returns retry opts                   | Params/headers merged from `retryOpts`                                          | User-controlled; `#checkFastLoop` on next iteration    |
+| L6  | `fetchSnapshot` catch → `fetchSnapshot` | 1975 | HTTP 409 on snapshot fetch                                 | New handle via `withHandle()`; unconditional cache buster on every 409          | `#maxSnapshotRetries` (5) + unconditional cache buster |
 
 ### Guard mechanisms
 
 | Guard                  | Scope                         | How it works                                                                                                                                     |
 | ---------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `#checkFastLoop`       | Non-live `#requestShape` only | Detects N requests at same offset within a time window. First: clears caches + resets. Persistent: exponential backoff → throws FetchError(502). |
 | `maxStaleCacheRetries` | Stale response path (L3)      | State machine counts stale retries. Throws FetchError(502) after 3 consecutive stale responses.                                                  |
-| `#maxSnapshotRetries`  | Snapshot 409 path (L6)        | Counts consecutive snapshot 409s. Adds cache buster when handle unchanged. Throws FetchError(502) after 5.                                       |
+| `#maxSnapshotRetries`  | Snapshot 409 path (L6)        | Counts consecutive snapshot 409s. Unconditional cache buster on every retry. Throws FetchError(502) after 5.                                     |
 | Pause lock             | `#requestShape` entry         | Returns immediately if paused. Prevents fetches during snapshots.                                                                                |
 | Up-to-date exit        | `#requestShape` entry         | Returns if `!subscribe` and `isUpToDate`. Breaks loop for one-shot syncs.                                                                        |
 

packages/typescript-client/src/constants.ts

@@ -35,6 +35,7 @@ export const CACHE_BUSTER_QUERY_PARAM = `cache-buster` // Random cache buster to
 export const ELECTRIC_PROTOCOL_QUERY_PARAMS: Array<string> = [
   LIVE_QUERY_PARAM,
   LIVE_SSE_QUERY_PARAM,
+  EXPERIMENTAL_LIVE_SSE_QUERY_PARAM,
   SHAPE_HANDLE_QUERY_PARAM,
   OFFSET_QUERY_PARAM,
   LIVE_CACHE_BUSTER_QUERY_PARAM,

packages/typescript-client/test/static-analysis.test.ts

@@ -124,6 +124,45 @@ describe(`shape-stream static analysis`, () => {
     }
   })
 
+  it(`includes all internal protocol QUERY_PARAM constants in ELECTRIC_PROTOCOL_QUERY_PARAMS`, async () => {
+    // Internal protocol params (handle, offset, cursor, live, etc.) must be
+    // listed in ELECTRIC_PROTOCOL_QUERY_PARAMS so that canonicalShapeKey
+    // strips them. Missing entries cause cache key divergence between code
+    // paths (e.g., SSE vs long-polling produce different shape keys).
+    //
+    // User-facing shape params (table, where, columns, replica) are
+    // intentionally excluded — they define the shape identity.
+    const constants = await import(`../src/constants`)
+    const protocolParams = new Set(constants.ELECTRIC_PROTOCOL_QUERY_PARAMS)
+
+    // User-facing params that define shape identity — NOT protocol internals
+    const userFacingParams = new Set([
+      `COLUMNS_QUERY_PARAM`,
+      `TABLE_QUERY_PARAM`,
+      `WHERE_QUERY_PARAM`,
+      `REPLICA_PARAM`, // not *_QUERY_PARAM but included for completeness
+      `WHERE_PARAMS_PARAM`,
+    ])
+
+    // Collect internal *_QUERY_PARAM exports
+    const internalParamExports = Object.entries(constants)
+      .filter(
+        ([key]) =>
+          key.endsWith(`_QUERY_PARAM`) &&
+          key !== `ELECTRIC_PROTOCOL_QUERY_PARAMS` &&
+          !userFacingParams.has(key)
+      )
+      .map(([key, value]) => ({ key, value: value as string }))
+
+    expect(internalParamExports.length).toBeGreaterThan(0)
+
+    const missing = internalParamExports.filter(
+      ({ value }) => !protocolParams.has(value)
+    )
+
+    expect(missing.map(({ key }) => key)).toEqual([])
+  })
+
   it(`reports near-miss Electric protocol literals`, async () => {
     const { analyzeProtocolLiterals } = await loadAnalyzerModule()
     const fixturePath = path.resolve(