docs(qwp): fix load-bearing concurrency comments that contradict the code

Five doc sites documented behavior the code deliberately does not have;
each invited a future 'fix' that would reintroduce the hazard the
quiescence work eliminated. Comment-only change.

- CursorSendEngine.closeCompleted field doc: carve the failed-flock-
  release case out of the retry sentence. A retried close() exits at the
  consumed terminalCleanupClaimed CAS and never calls SlotLock.release()
  again — deliberate, pinned by
  testUnconfirmedFlockReleaseKeepsCloseIncomplete.
- CursorSendEngine.finishClose javadoc: 'must hold the engine monitor'
  was false for completeDeferredClose (deliberately monitor-free to
  avoid the join livelock). State the real contract: monitor (close
  path) OR worker exit path; in all cases the CAS must be won.
- CursorSendEngine.isCloseCompleted javadoc: admit the third,
  unrecoverable state — failed flock release never flips; only process
  exit frees the flock.
- SegmentManager.isWorkerReaped javadoc: the fall-through reap nulls
  workerThread while the thread may still be running deferred engine
  cleanups; the engine-side CAS, not this predicate, is the exclusion.
- SegmentManager.serviceRing0 trim comment: narrow 'stale snapshots' to
  mid-pass-deregistered entries — the claim gate makes the trim block
  unreachable for pre-pass-deregistered entries.
- SenderPool reclaimSlot/retireLease: 'retired permanently' contradicted
  retiredSlots.add + reprobeRetiredSlots recovery three lines down.
- QwpWebSocketSender post-guard comment: the incomplete-close branch is
  not only the owned-manager handoff; document the no-handoff cases
  (shared manager, failed handoff registration, failed flock release)
  where the re-probe never flips.

Author: bluestreak01

core/src/main/java/io/questdb/client/cutlass/qwp/client/QwpWebSocketSender.java

@@ -1272,13 +1272,21 @@ public void close() {
                     ownsCursorEngine = false;
                     slotLockReleased = true;
                 } else {
-                    // The manager worker did not quiesce. Preserve ownership
-                    // and report the retained flock so pools retire this slot.
-                    // Repeated Sender.close() calls remain no-ops by contract.
-                    // Engine cleanup was handed to the worker's exit path
-                    // (owned manager); the getter re-probes the retained
-                    // engine so the pool can reclaim the slot once cleanup
-                    // actually completes.
+                    // Engine close() could not confirm a released flock.
+                    // Preserve ownership and report the retained flock so
+                    // pools retire this slot. Repeated Sender.close() calls
+                    // remain no-ops by contract. Recovery depends on WHY the
+                    // close is incomplete: when cleanup was handed to the
+                    // worker's exit path (owned manager — the only shipping
+                    // configuration), isSlotLockReleased()'s re-probe of the
+                    // retained engine flips once that cleanup completes.
+                    // When there was no handoff, the re-probe never flips
+                    // and the slot stays retired until process exit: a
+                    // shared-manager engine or a failed handoff registration
+                    // needs a retried engine.close() that this one-shot
+                    // sender never issues, and a failed flock release has
+                    // consumed the engine's cleanup claim, so nothing can
+                    // re-run the release.
                     slotLockReleased = false;
                     retainedEngine = engine;
                 }

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

@@ -124,9 +124,16 @@ public final class CursorSendEngine implements QuietCloseable {
     // SenderPool.reprobeRetiredSlots), so publishing before the release
     // would let a replacement engine's SlotLock.acquire collide with the
     // still-open fd. Stays false when a close attempt could not confirm
-    // manager-worker quiescence (or the flock release itself failed) and had
-    // to leak the ring/watermark/slot lock — in that case a later close()
-    // call retries the cleanup (the worker may have exited by then).
+    // manager-worker quiescence and had to leak the ring/watermark/slot
+    // lock — in that case a later close() call retries the cleanup (the
+    // worker may have exited by then). Also stays false — permanently —
+    // when finishClose() ran but the flock release itself failed: the
+    // terminalCleanupClaimed CAS is consumed, so a retried close() exits at
+    // the CAS without re-running the cleanup or calling SlotLock.release()
+    // again. That non-retry is deliberate (a retry would double-close the
+    // ring/watermark and double-release the flock; pinned by
+    // testUnconfirmedFlockReleaseKeepsCloseIncomplete) — the kernel drops
+    // the flock at process exit.
     // volatile: latched by finishClose(), but read lock-free by
     // isCloseCompleted() from pool threads re-probing a retired slot (see the
     // getter for why it must not synchronize).
@@ -674,7 +681,10 @@ public synchronized void close() {
      * {@code closeCompleted} (via {@code isSlotLockReleased()}), so it must
      * never be visible while the flock fd is still open, or a replacement
      * engine races the release and fails acquisition on a live slot.
-     * The caller must hold the engine monitor and
+     * The caller must either hold the engine monitor (the close() path) or
+     * run on the manager worker's exit path ({@link #completeDeferredClose},
+     * which deliberately takes no monitor — adding one would recreate the
+     * join livelock the CAS exists to avoid); in all cases the caller
      * must have established that the manager worker can no longer touch the
      * slot directory (reaped, provably exited, or running this on its own
      * exit path) AND have won the {@link #terminalCleanupClaimed} CAS — the
@@ -796,11 +806,14 @@ private void completeDeferredClose(boolean fullyDrained) {
      * <b>confirmed</b> release of the SF slot lock — the flip is published
      * strictly after the flock fd is closed, so observing {@code true}
      * guarantees the slot dir is acquirable by a replacement engine. A false
-     * value after close means manager-worker quiescence could not be
-     * confirmed (or the flock release itself failed) and the
-     * worker-reachable resources were retained deliberately — either handed to the worker's exit path (owned manager),
-     * which flips this to true the moment the worker's in-flight pass
-     * finishes, or leaked until a retried close() (shared manager). Owners
+     * value after close means the worker-reachable resources were retained
+     * deliberately, for one of three reasons: cleanup was handed to the
+     * worker's exit path (owned manager), which flips this to true the
+     * moment the worker's in-flight pass finishes; cleanup was leaked until
+     * a retried close() (shared manager, or a failed handoff registration);
+     * or the flock release itself failed — that last case never flips: the
+     * {@link #terminalCleanupClaimed} CAS is consumed, so no retry re-runs
+     * the release, and only process exit frees the flock. Owners
      * must not reuse the slot while this is false; pools may re-probe it to
      * recover a retired slot's capacity once it flips.
      * <p>

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

@@ -376,9 +376,16 @@ public boolean awaitRingQuiescence(SegmentRing ring) {
     }
 
     /**
-     * True when no manager worker thread can be running: either
-     * {@link #start()} was never called, or a {@link #close()} confirmed
-     * worker termination and reaped the thread. Owners use this as a
+     * True when the manager worker can no longer run a service pass: either
+     * {@link #start()} was never called, or a {@link #close()} reaped the
+     * thread — including the fall-through reap that observes
+     * {@code workerLoopExited} while the thread is still alive. In that case
+     * the worker may still be RUNNING its deferred engine cleanups
+     * (see {@link #deferUntilWorkerExit}: munmap/unlink/flock-release on the
+     * exit path) when this flips true, so this predicate is NOT the
+     * exclusion between a retried engine close() and the worker's deferred
+     * cleanup — the engine-side {@code terminalCleanupClaimed} CAS is.
+     * Owners use this as a
      * stronger fallback barrier when {@link #awaitRingQuiescence(SegmentRing)}
      * times out but a subsequent {@code close()} join succeeded.
      */
@@ -742,7 +749,10 @@ private void serviceRing0(RingEntry e) {
         //    The watermark write and totalBytes commit are registration-gated
         //    under `lock` so stale worker snapshots cannot touch the
         //    engine-owned watermark or mutate accounting after deregister()
-        //    returns. drainTrimmable still runs for stale snapshots: it
+        //    returns. drainTrimmable still runs for entries deregistered
+        //    MID-pass (entries deregistered before the pass started never
+        //    get here — the registration/in-service claim at the top of
+        //    serviceRing skips them entirely): it
         //    transfers ownership of fully-acked sealed segments to this
         //    worker, preserving the old close + unlink behavior.
         //

core/src/main/java/io/questdb/client/impl/SenderPool.java

@@ -1062,7 +1062,9 @@ private void retireLease(PooledSender ps, String context) {
                 pendingLeaseTeardowns--;
                 if (reserved) {
                     // Free the index only when the flock was released; a slot
-                    // left locked is retired permanently.
+                    // left locked is retired into retiredSlots, recoverable
+                    // by reprobeRetiredSlots() if the deferred cleanup drops
+                    // the flock later.
                     reclaimSlot(s, context);
                 }
                 slotReleased.signalAll();
@@ -1350,10 +1352,13 @@ private static boolean flockReleased(SenderSlot s) {
      * Reclaims one SF slot after its delegate's {@code close()} has been
      * attempted. When the flock was released the index returns to the free
      * set; when {@code close()} returned with the flock still held because an
-     * I/O or manager worker did not stop, the slot is retired permanently --
-     * {@code leakedSlots++} and {@code slotInUse[idx]} stays set -- so the cap
-     * math accounts for the lost capacity and no later borrow ever reuses the
-     * still-locked dir. Either way {@code closingSlots} is decremented.
+     * I/O or manager worker did not stop, the slot is retired --
+     * {@code leakedSlots++}, {@code slotInUse[idx]} stays set, and the sender
+     * joins {@code retiredSlots} -- so the cap math accounts for the lost
+     * capacity and no borrow reuses the still-locked dir unless
+     * {@link #reprobeRetiredSlots} later observes the deferred cleanup's
+     * release and recovers the index. Either way {@code closingSlots} is
+     * decremented.
      * <p>
      * Caller must hold {@code lock} and is responsible for signalling waiters
      * (only the free path admits a new creation). Shared by