Correct stale and stranded symbol-dict comments

Comment-only follow-ups from the delta symbol-dict review; no behaviour
change.

- quarantineTornSlot marks the set-aside slot .failed unconditionally, so
  the orphan drainer never re-examines it. Fix the two comments that
  claimed the drainer could still deliver a quarantined slot; state that
  it is a human-in-the-loop copy whose bytes are kept for a manual resend.

- sendCommitMessage's full-dict-mode comment claimed the commit frame
  stays self-sufficient, but the prior flush reset currentBatchMaxSymbolId
  to -1, so the frame carries an empty delta. Say so -- it is harmless,
  the preceding data frames already registered the dictionary.

- Move three javadoc blocks stranded above the wrong method back onto
  their own: MmapSegment.maxSymbolDeltaEnd, SegmentRing.maxSymbolDeltaEnd
  and Sender.closeFlushTimeoutMillis were left undocumented, and the
  stranded @param names no longer matched the method beneath them.

- Drop a double blank line in CursorSendEngine.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: glasstiger

core/src/main/java/io/questdb/client/Sender.java

@@ -1013,8 +1013,9 @@ final class LineSenderBuilder {
         private static final int PROTOCOL_UDP = 3;
         private static final int PROTOCOL_WEBSOCKET = 2;
         // Suffix for a slot set aside by quarantineTornSlot. Deliberately NOT the
-        // sender's own slot name, so OrphanScanner sees the quarantined copy and the
-        // orphan drainer can still deliver it if its frames turn out to be replayable.
+        // sender's own slot name, so a restarted sender does not re-adopt it as its own;
+        // quarantineTornSlot then marks it .failed, so the orphan drainer skips it too and
+        // the bytes stay put for a human to inspect and resend.
         private static final String QUARANTINE_SLOT_SUFFIX = ".unreplayable-";
         private final ObjList<String> hosts = new ObjList<>();
         private final IntList ports = new IntList();
@@ -1757,23 +1758,6 @@ public Sender build() {
             return sender;
         }
 
-        /**
-         * close() drain timeout in milliseconds. The sender's {@code close()}
-         * method blocks up to this many millis waiting for the server to ACK
-         * every batch already published into the engine before shutting down
-         * the I/O loop. Default {@code 60000} (60 s) -- generous enough to
-         * survive real-workload backlogs (slow consumers, catch-up replicas,
-         * chunky payloads on small server send buffers) without silently
-         * dropping unacked rows; callers that need a longer pre-close wait
-         * for a specific submission can call
-         * {@link Sender#drain(long)} explicitly before close().
-         * <p>
-         * Set to {@code 0} or {@code -1} to opt out — close() will not wait
-         * at all (fast close). Pending data is then lost in memory mode and
-         * recovered by the next sender in SF mode.
-         * <p>
-         * WebSocket transport only.
-         */
         /**
          * Minimum wall-clock time (millis) a symbol-dictionary catch-up CAP GAP must
          * persist before the sender gives up on it and fails.
@@ -1805,6 +1789,23 @@ public LineSenderBuilder catchUpCapGapMinEscalationWindowMillis(long millis) {
             return this;
         }
 
+        /**
+         * close() drain timeout in milliseconds. The sender's {@code close()}
+         * method blocks up to this many millis waiting for the server to ACK
+         * every batch already published into the engine before shutting down
+         * the I/O loop. Default {@code 60000} (60 s) -- generous enough to
+         * survive real-workload backlogs (slow consumers, catch-up replicas,
+         * chunky payloads on small server send buffers) without silently
+         * dropping unacked rows; callers that need a longer pre-close wait
+         * for a specific submission can call
+         * {@link Sender#drain(long)} explicitly before close().
+         * <p>
+         * Set to {@code 0} or {@code -1} to opt out — close() will not wait
+         * at all (fast close). Pending data is then lost in memory mode and
+         * recovered by the next sender in SF mode.
+         * <p>
+         * WebSocket transport only.
+         */
         public LineSenderBuilder closeFlushTimeoutMillis(long timeoutMillis) {
             if (protocol != PARAMETER_NOT_SET_EXPLICITLY && protocol != PROTOCOL_WEBSOCKET) {
                 throw new LineSenderException("close_flush_timeout_millis is only supported for WebSocket transport");
@@ -3019,13 +3020,17 @@ private static long parseSizeValue(@NotNull StringSink value, @NotNull String na
          * already-lost batch for an unbounded outage of everything after it, which inverts
          * the one guarantee store-and-forward exists to give.
          * <p>
-         * So: rename the slot aside instead. The bytes are preserved for forensics and for
-         * the orphan drainer, which reaches the same verdict independently (its send loop's
-         * replay guard fires and it marks the slot {@code .failed}) -- and which, on a slot
-         * that turns out to be drainable after all (frames written in full-dictionary
-         * fallback mode are self-sufficient), simply drains it. The new name is NOT the
-         * sender's own slot name, so {@code OrphanScanner} will consider it. The producer,
-         * meanwhile, starts on a clean empty slot and never notices.
+         * So: rename the slot aside instead, and mark it {@code .failed}. The verdict is
+         * authoritative -- the recovery seed already tried every source of truth (the
+         * persisted prefix AND the surviving frames' own deltas), and the orphan drainer's
+         * own replay guard uses that same walk, so there is nothing a drainer could rebuild
+         * that the seed did not. {@code markFailed} (below) therefore quarantines the copy
+         * for a human rather than leaving a drainer to retry an unreplayable slot forever;
+         * a full-dictionary-fallback slot never reaches here, because its dictionary is
+         * discarded at recovery and it never throws. The bytes are preserved on disk for
+         * forensics and a manual resend, and the new name -- NOT the sender's own slot name
+         * -- keeps a restarted sender from re-adopting it. The producer, meanwhile, starts
+         * on a clean empty slot and never notices.
          * <p>
          * If the rename fails (a Windows share lock, a read-only mount) there is no way to
          * free the slot name without destroying data, so fall back to the old behaviour and

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

@@ -3751,7 +3751,9 @@ private void sendCommitMessage() {
         // what has already been sent -- and therefore already persisted. In delta
         // mode pass sentMaxSymbolId, yielding an empty delta
         // [sentMaxSymbolId+1 .. sentMaxSymbolId]; in full-dict mode keep
-        // currentBatchMaxSymbolId so the frame stays self-sufficient. Any symbol a
+        // currentBatchMaxSymbolId (reset to -1 by the prior flush, so the commit frame
+        // carries an empty delta too -- harmless, since the preceding full-dict data
+        // frames already registered the dictionary on this connection). Any symbol a
         // cancelled row leaked is picked up (and persisted) by the next real flush,
         // whose persistNewSymbolsBeforePublish resumes from pd.size().
         int commitBatchMaxId = deltaDictEnabled ? sentMaxSymbolId : currentBatchMaxSymbolId;

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

@@ -783,7 +783,6 @@ public boolean isDeltaDictEnabled() {
         return sfDir == null || persistedSymbolDict != null;
     }
 
-
     /**
      * Pass-through to {@link SegmentRing#nextSealedAfter(MmapSegment)}.
      */

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

@@ -524,37 +524,6 @@ public long findLastFrameFsnWithoutPayloadFlag(int flagsOffset, int flagMask, in
         return best;
     }
 
-    /**
-     * Highest {@code deltaStart + deltaCount} (one past the highest symbol id) any
-     * delta-flagged frame in this segment carries, or {@code 0} only when NO
-     * delta-flagged frame is present. A frame with {@code deltaCount == 0} (a commit
-     * or a symbol-reusing frame -- the encoder always sets the delta flag) still
-     * contributes its {@code deltaStart}, i.e. the producer's baseline at encode
-     * time, NOT 0. That is deliberate: it anchors the torn-dict guard at that
-     * baseline so a dictionary torn below it is detected -- a conservative
-     * over-strand (it may over-reject a frame whose rows reference only surviving
-     * ids), never an under-strand that could silently shift the dense id map.
-     * Read-only walk over the recovered frames, used
-     * once at recovery to detect a persisted {@code .symbol-dict} torn (host crash,
-     * out-of-order page loss) below the ids the surviving frames still reference: if
-     * the max here reaches at or beyond the recovered dictionary size, a resuming
-     * producer -- seeded from the shorter dictionary -- would re-use ids the frames
-     * already define. Only frames at or below {@code maxFsnInclusive} count: frames
-     * above it are the aborted orphan-deferred tail, which {@code trySendOne} retires
-     * without ever transmitting, so their ids must not inflate the result (a resuming
-     * producer never reuses them on the wire). The frame layout mirrors
-     * {@link #findLastFrameFsnWithoutPayloadFlag}: the QWP message header
-     * ({@code qwpHeaderSize} bytes) is followed by the delta section
-     * {@code [deltaStart varint][deltaCount varint]...}.
-     *
-     * @param headerMagic     the QWP message magic identifying a well-formed frame
-     * @param flagsOffset     byte offset of the flags field within the QWP header
-     * @param flagDeltaMask   the FLAG_DELTA_SYMBOL_DICT bit
-     * @param qwpHeaderSize   the QWP message header size (delta section starts past it)
-     * @param maxFsnInclusive highest frame FSN to consider; frames above it are the
-     *                        retired orphan-deferred tail -- pass
-     *                        {@code recoveredCommitBoundaryFsn}
-     */
     /**
      * Rebuilds, from the frames' own delta sections, the symbols a replay of
      * {@code [minFsnInclusive .. maxFsnInclusive]} would register ABOVE {@code coverage},
@@ -670,6 +639,37 @@ public long collectReplaySymbolsAbove(
         return coverage;
     }
 
+    /**
+     * Highest {@code deltaStart + deltaCount} (one past the highest symbol id) any
+     * delta-flagged frame in this segment carries, or {@code 0} only when NO
+     * delta-flagged frame is present. A frame with {@code deltaCount == 0} (a commit
+     * or a symbol-reusing frame -- the encoder always sets the delta flag) still
+     * contributes its {@code deltaStart}, i.e. the producer's baseline at encode
+     * time, NOT 0. That is deliberate: it anchors the torn-dict guard at that
+     * baseline so a dictionary torn below it is detected -- a conservative
+     * over-strand (it may over-reject a frame whose rows reference only surviving
+     * ids), never an under-strand that could silently shift the dense id map.
+     * Read-only walk over the recovered frames, used
+     * once at recovery to detect a persisted {@code .symbol-dict} torn (host crash,
+     * out-of-order page loss) below the ids the surviving frames still reference: if
+     * the max here reaches at or beyond the recovered dictionary size, a resuming
+     * producer -- seeded from the shorter dictionary -- would re-use ids the frames
+     * already define. Only frames at or below {@code maxFsnInclusive} count: frames
+     * above it are the aborted orphan-deferred tail, which {@code trySendOne} retires
+     * without ever transmitting, so their ids must not inflate the result (a resuming
+     * producer never reuses them on the wire). The frame layout mirrors
+     * {@link #findLastFrameFsnWithoutPayloadFlag}: the QWP message header
+     * ({@code qwpHeaderSize} bytes) is followed by the delta section
+     * {@code [deltaStart varint][deltaCount varint]...}.
+     *
+     * @param headerMagic     the QWP message magic identifying a well-formed frame
+     * @param flagsOffset     byte offset of the flags field within the QWP header
+     * @param flagDeltaMask   the FLAG_DELTA_SYMBOL_DICT bit
+     * @param qwpHeaderSize   the QWP message header size (delta section starts past it)
+     * @param maxFsnInclusive highest frame FSN to consider; frames above it are the
+     *                        retired orphan-deferred tail -- pass
+     *                        {@code recoveredCommitBoundaryFsn}
+     */
     public long maxSymbolDeltaEnd(int headerMagic, int flagsOffset, int flagDeltaMask, int qwpHeaderSize, long maxFsnInclusive) {
         long maxEnd = 0L;
         long off = HEADER_SIZE;

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

@@ -546,14 +546,6 @@ public synchronized long findLastFsnWithoutPayloadFlag(int flagsOffset, int flag
         return Math.max(best, fsn);
     }
 
-    /**
-     * Highest {@code deltaStart + deltaCount} any symbol-dict delta frame at or below
-     * {@code maxFsnInclusive} references (0 when none). See
-     * {@link MmapSegment#maxSymbolDeltaEnd}; used once at recovery to detect a
-     * persisted dictionary torn below the ids the surviving committed frames
-     * reference. Frames above {@code maxFsnInclusive} are the retired orphan-deferred
-     * tail and are excluded.
-     */
     /**
      * Rebuilds the symbols a replay of {@code [minFsnInclusive .. maxFsnInclusive]} would
      * register ABOVE {@code baseline}, appending them to {@code out} in ascending id order.
@@ -589,6 +581,14 @@ public synchronized long collectReplaySymbolsAbove(
                 minFsnInclusive, maxFsnInclusive, coverage, out);
     }
 
+    /**
+     * Highest {@code deltaStart + deltaCount} any symbol-dict delta frame at or below
+     * {@code maxFsnInclusive} references (0 when none). See
+     * {@link MmapSegment#maxSymbolDeltaEnd}; used once at recovery to detect a
+     * persisted dictionary torn below the ids the surviving committed frames
+     * reference. Frames above {@code maxFsnInclusive} are the retired orphan-deferred
+     * tail and are excluded.
+     */
     public synchronized long maxSymbolDeltaEnd(int headerMagic, int flagsOffset, int flagDeltaMask, int qwpHeaderSize, long maxFsnInclusive) {
         long maxEnd = 0L;
         for (int i = 0, n = sealedSegments.size(); i < n; i++) {