docs(qwp): align reconnect-budget docs with Invariant B; mark dead field

Documentation-only cleanup after the Invariant B fix (no behavior change):

- CursorWebSocketSendLoop: correct the class + fail() javadoc that still said
  the reconnect loop is "time-capped at reconnect_max_duration_millis". It now
  retries indefinitely (capped exponential backoff); only auth/upgrade rejects
  or SF exhaustion are terminal.
- CursorWebSocketSendLoop: comment the now-dead reconnectMaxDurationMillis
  field -- retained for constructor symmetry / caller API, but no longer read
  by connectLoop. The budget still bounds the blocking (non-lazy) initial
  connect via connectWithRetry, which takes it as an explicit argument.
- BackgroundDrainer: clarify that the wall-clock budget + 16-attempt cap apply
  ONLY to a genuine durable-ack capability gap; a transient all-replica
  failover window is retried indefinitely and never quarantined.

Author: bluestreak01

core/src/main/java/io/questdb/client/cutlass/qwp/client/sf/cursor/BackgroundDrainer.java

@@ -52,22 +52,28 @@
  *   <li>Close everything in reverse order; release the lock.</li>
  * </ol>
  * <p>
- * On terminal failure (auth-rejection on reconnect, reconnect-budget
- * exhaustion, recovery error), the drainer drops a
- * {@link OrphanScanner#FAILED_SENTINEL_NAME} sentinel into the slot
- * before exiting. Future scans skip the slot until an operator clears
- * the sentinel — bounded automatic retry, then human-in-the-loop.
+ * On terminal failure (auth-rejection on reconnect, a cluster-wide durable-ack
+ * capability gap that exhausts its settle budget, recovery error), the drainer
+ * drops a {@link OrphanScanner#FAILED_SENTINEL_NAME} sentinel into the slot
+ * before exiting. Future scans skip the slot until an operator clears the
+ * sentinel — bounded automatic retry, then human-in-the-loop. A transient
+ * all-replica failover window is NOT terminal: it is retried indefinitely
+ * (Invariant B), never quarantined on a wall-clock budget or attempt cap.
  */
 public final class BackgroundDrainer implements Runnable {
 
     /**
      * Cap on consecutive {@link QwpDurableAckMismatchException} attempts at
      * initial connect before the drainer escalates to a {@code .failed}
-     * sentinel. The wall-clock budget {@code reconnectMaxDurationMillis}
-     * also caps the same loop; whichever is hit first triggers escalation.
-     * 16 attempts gives the cluster room to settle through a rolling
-     * upgrade (each attempt walks every endpoint internally) without
-     * letting a genuine cluster-wide misconfig hang the drainer forever.
+     * sentinel. Applies ONLY to a genuine cluster-wide durable-ack capability
+     * gap (a server that upgrades but does not advertise durable ack); a
+     * transient all-replica failover window (role reject) is retried
+     * indefinitely and is never subject to this cap (Invariant B). The
+     * wall-clock budget {@code reconnectMaxDurationMillis} also caps this
+     * capability-gap loop; whichever is hit first triggers escalation. 16
+     * attempts gives the cluster room to settle through a rolling upgrade
+     * (each attempt walks every endpoint internally) without letting a genuine
+     * cluster-wide misconfig hang the drainer forever.
      */
     public static final int DEFAULT_MAX_DURABLE_ACK_MISMATCH_ATTEMPTS = 16;
     private static final Logger LOG = LoggerFactory.getLogger(BackgroundDrainer.class);

core/src/main/java/io/questdb/client/cutlass/qwp/client/sf/cursor/CursorWebSocketSendLoop.java

@@ -61,10 +61,11 @@
  *       cumulative wire sequence {@code N}, calls
  *       {@code engine.acknowledge(fsnAtZero + N)} so the segment manager
  *       can trim fully-acked segments.</li>
- *   <li>On wire failure, runs the configured reconnect policy: backoff
- *       with jitter up to {@code reconnect_max_duration_millis}, with
- *       auth-style failures (401/403/non-101 upgrade reject) treated as
- *       terminal. On reconnect success, repositions the cursor at
+ *   <li>On wire failure, runs the configured reconnect policy: capped
+ *       exponential backoff with jitter, retried indefinitely (Invariant B --
+ *       a store-and-forward drainer never gives up on a wall-clock budget),
+ *       with only auth-style failures (401/403/non-101 upgrade reject) treated
+ *       as terminal. On reconnect success, repositions the cursor at
  *       {@code ackedFsn+1} and replays.</li>
  * </ol>
  * No locks on the steady-state path. The producer thread (user) writes
@@ -140,6 +141,11 @@ public final class CursorWebSocketSendLoop implements QuietCloseable {
     private final ReconnectFactory reconnectFactory;
     private final long reconnectInitialBackoffMillis;
     private final long reconnectMaxBackoffMillis;
+    // Retained for constructor symmetry and passed in by callers, but NOT
+    // consulted by the background loop: Invariant B removed the wall-clock
+    // give-up from connectLoop. The budget still bounds the blocking (non-lazy)
+    // initial connect via QwpWebSocketSender -> connectWithRetry, which takes it
+    // as an explicit argument rather than reading this field.
     private final long reconnectMaxDurationMillis;
     private final WebSocketResponse response = new WebSocketResponse();
     private final ResponseHandler responseHandler = new ResponseHandler();
@@ -1019,12 +1025,12 @@ private void enqueuePendingOk(long wireSeq) {
 
     /**
      * Surface a wire failure. With reconnect plumbing wired (factory +
-     * listener both non-null), enters the per-outage retry loop:
-     * exponential backoff with jitter, time-capped at
-     * {@code reconnectMaxDurationMillis}, terminal on auth/upgrade
-     * rejections (so the budget isn't burned on errors that won't fix
-     * themselves). On the first successful reconnect within the budget,
-     * the I/O loop resumes with reset wire state and replays from
+     * listener both non-null), enters the per-outage retry loop: capped
+     * exponential backoff with jitter, retried for as long as the loop is
+     * running -- there is NO wall-clock give-up (Invariant B: a store-and-
+     * forward drainer only terminates on SF exhaustion or a genuinely non-
+     * retriable auth/upgrade reject). On the first successful reconnect the
+     * I/O loop resumes with reset wire state and replays from
      * {@code engine.ackedFsn() + 1}.
      * <p>
      * Without reconnect plumbing, the failure is immediately terminal