fix(client): warn loudly when self-healing accepts stale proxy data

Addresses three findings from external review of the self-healing PR:

1. Detect and warn when a post-self-heal response carries the same
   handle we just marked expired. Previously the client silently
   accepted stale data with no operator signal — now it emits a
   targeted warning naming the handle and pointing at the proxy
   cache-key misconfiguration that causes this.

2. Tighten the recovery-guard clearing check from
   `accepted + kind === live` to an explicit `status === 204`, matching
   the comment's intent and removing latent fragility if the state
   machine ever starts transitioning to live for non-204 responses.

3. Update the `#reset()` comment to list all three callers
   (#requestShape's 409 handler, #checkFastLoop, and stale-retry
   self-healing) instead of only the 409 handler.

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

Author: KyleAMathews

packages/typescript-client/src/client.ts

@@ -624,6 +624,7 @@ export class ShapeStream<T extends Row<unknown> = Row>
   #pendingRequestShapeCacheBuster?: string
   #maxSnapshotRetries = 5
   #expiredShapeRecoveryKey: string | null = null
+  #pendingSelfHealCheck: { shapeKey: string; staleHandle: string } | null = null
 
   constructor(options: ShapeStreamOptions<GetExtensions<T>>) {
     this.options = { subscribe: true, ...options }
@@ -1225,6 +1226,25 @@ export class ShapeStream<T extends Row<unknown> = Row>
       ? expiredShapesCache.getExpiredHandle(shapeKey)
       : null
 
+    // If this response is the first one after a self-healing retry, check
+    // whether the proxy/CDN returned the exact handle we just marked expired.
+    // If so, the client is about to accept stale data silently — loudly warn
+    // so operators can detect and fix the proxy misconfiguration.
+    if (this.#pendingSelfHealCheck) {
+      const { shapeKey: healedKey, staleHandle } = this.#pendingSelfHealCheck
+      this.#pendingSelfHealCheck = null
+      if (shapeKey === healedKey && shapeHandle === staleHandle) {
+        console.warn(
+          `[Electric] Self-healing retry received the same handle "${staleHandle}" that was just marked expired. ` +
+            `This means your proxy/CDN is serving a stale cached response and ignoring cache-buster query params. ` +
+            `The client will proceed with this stale data to avoid a permanent failure, but it may be out of date until the cache refreshes. ` +
+            `Fix: configure your proxy/CDN to include all query parameters (especially 'handle' and 'offset') in its cache key. ` +
+            `For more information visit the troubleshooting guide: ${TROUBLESHOOTING_URL}`,
+          new Error(`stack trace`)
+        )
+      }
+    }
+
     const transition = this.#syncState.handleResponseMetadata({
       status,
       responseHandle: shapeHandle,
@@ -1239,9 +1259,9 @@ export class ShapeStream<T extends Row<unknown> = Row>
 
     this.#syncState = transition.state
 
-    // Clear recovery guard when response transitions directly to live (e.g. 204),
-    // since #onMessages won't run for empty bodies.
-    if (transition.action === `accepted` && this.#syncState.kind === `live`) {
+    // Clear recovery guard on 204 (no-content), since the empty body means
+    // #onMessages won't run to clear it via the up-to-date path.
+    if (status === 204) {
       this.#expiredShapeRecoveryKey = null
     }
 
@@ -1265,6 +1285,16 @@ export class ShapeStream<T extends Row<unknown> = Row>
               new Error(`stack trace`)
             )
             this.#expiredShapeRecoveryKey = shapeKey
+            // Arm a post-self-heal check: if the next response comes back
+            // with the same handle we just marked expired, the proxy/CDN is
+            // still serving stale data and we'll warn loudly instead of
+            // accepting it silently.
+            if (shapeHandle) {
+              this.#pendingSelfHealCheck = {
+                shapeKey,
+                staleHandle: shapeHandle,
+              }
+            }
             this.#reset()
             throw new StaleCacheError(
               `Expired handle entry evicted for self-healing retry`
@@ -1770,9 +1800,10 @@ export class ShapeStream<T extends Row<unknown> = Row>
   #reset(handle?: string) {
     this.#syncState = this.#syncState.markMustRefetch(handle)
     this.#connected = false
-    // releaseAllMatching intentionally doesn't fire onReleased — it's called
-    // from within the running stream loop (#requestShape's 409 handler), so
-    // the stream is already active and doesn't need a resume signal.
+    // releaseAllMatching intentionally doesn't fire onReleased — every caller
+    // (#requestShape's 409 handler, #checkFastLoop, and stale-retry
+    // self-healing in #onInitialResponse) runs inside the active stream loop,
+    // so the stream is already active and doesn't need a resume signal.
     this.#pauseLock.releaseAllMatching(`snapshot`)
   }
 

packages/typescript-client/test/expired-shapes-cache.test.ts

@@ -673,11 +673,13 @@ describe(`ExpiredShapesCache`, () => {
     expect(expiredShapesCache.getExpiredHandle(expectedShapeUrl)).toBeNull()
   })
 
-  it(`self-healing accepts stale data when proxy always serves expired handle (by design)`, async () => {
+  it(`self-healing accepts stale data when proxy always serves expired handle (by design) but warns loudly`, async () => {
     // Finding 1 from external review: after self-healing clears the expired
     // entry, if the proxy serves the same stale response with up-to-date,
     // the client accepts it. This is by design — stale data is better than
-    // permanent 502 for one-shot streams.
+    // permanent 502 for one-shot streams — but the client MUST warn loudly
+    // so operators can detect and fix the proxy misconfiguration.
+    const warnSpy = vi.spyOn(console, `warn`).mockImplementation(() => {})
     const expectedShapeUrl = `${shapeUrl}?table=test`
     const staleHandle = `expired-handle`
 
@@ -744,6 +746,20 @@ describe(`ExpiredShapesCache`, () => {
     expect(stream.isUpToDate).toBe(true)
     // 4 stale retries + 1 self-healing = 5
     expect(requestCount).toBe(5)
+
+    // CRITICAL: silent acceptance of stale data would be a bug. The client
+    // MUST emit a warning naming the stale handle so operators can detect
+    // and fix the proxy misconfiguration. Without this signal, apps would
+    // sit on stale data with no way to know.
+    const staleAcceptWarning = warnSpy.mock.calls.find(
+      (args) =>
+        typeof args[0] === `string` &&
+        args[0].includes(
+          `Self-healing retry received the same handle "${staleHandle}"`
+        )
+    )
+    expect(staleAcceptWarning).toBeTruthy()
+    warnSpy.mockRestore()
   })
 
   it(`should clear recovery guard after 204 so self-healing works again`, async () => {