Defer catch-up commit; fix stale delta comments

Three delta symbol-dict cleanups (a fourth reported item, a dead
CursorSendEngine.isMemoryMode(), was already removed earlier on this
branch, so nothing to do there):

- sendCatchUpChunk now sets FLAG_DEFER_COMMIT on the catch-up frame. It
  carries dictionary entries but no rows, so it must never trigger a
  server-side commit. Today it is always the first frame on a fresh
  (empty-transaction) connection, so committing nothing is a no-op -- but
  that invariant is load-bearing and was unasserted. Deferring the empty
  commit removes the dependency, so a future mid-stream catch-up cannot
  prematurely commit an in-flight deferred transaction. The dictionary
  delta still registers, as any deferred data frame's does.

- flushPendingRows' comment claimed delta mode is "memory-mode only";
  file-mode store-and-forward ships monotonic deltas too once the
  persisted dictionary opened. Corrected.

- The deltaDictEnabled field comment implied delta mode only applies to
  recovered / orphan-drained disk slots; it applies to fresh disk slots
  too. Clarified that recovery additionally seeds the mirror.

testReconnectCatchUpRebuildsDictionary now asserts the catch-up frame
carries FLAG_DEFER_COMMIT; it fails without the flag.

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

Author: glasstiger

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

@@ -3455,7 +3455,8 @@ private void flushPendingRows(boolean deferCommit) {
         ensureActiveBufferReady();
         // In full-dict mode every frame is self-sufficient: it carries the whole
         // symbol dictionary from id 0 so orphan-drain / recovery replay to a fresh
-        // server never dangles a symbol id. In delta mode (memory-mode only) each
+        // server never dangles a symbol id. In delta mode (memory-mode, and
+        // file-mode store-and-forward once the persisted dictionary opened) each
         // frame carries only ids above sentMaxSymbolId; a reconnect re-registers
         // the dictionary via an I/O-thread catch-up frame before replay, so the
         // producer's monotonic baseline stays valid across the wire boundary.

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

@@ -187,8 +187,11 @@ public final class CursorWebSocketSendLoop implements QuietCloseable {
     private final WebSocketResponse response = new WebSocketResponse();
     private final ResponseHandler responseHandler = new ResponseHandler();
     // Delta symbol dictionary catch-up state (see swapClient). Active in memory
-    // mode, and in disk mode on a recovered / orphan-drained slot (the constructor
-    // seeds sentDict* from the persisted dictionary there).
+    // mode, and in disk mode whenever the per-slot persisted dictionary opened --
+    // fresh slots included, not just recovered / orphan-drained ones. On a
+    // recovered / orphan-drained slot the constructor additionally SEEDS sentDict*
+    // from that persisted dictionary; a fresh slot starts with an empty mirror and
+    // grows it as frames are sent.
     // deltaDictEnabled gates all of it. The loop mirrors, in sentDict*, every
     // symbol it has ever sent -- the concatenated [len varint][utf8] bytes in
     // global-id order (sentDictBytes*) plus the count (sentDictCount) -- so that
@@ -2293,8 +2296,18 @@ private void sendCatchUpChunk(int deltaStart, int deltaCount, long symbolsAddr,
             Unsafe.getUnsafe().putByte(frame + 2, (byte) 'P');
             Unsafe.getUnsafe().putByte(frame + 3, (byte) '1');
             Unsafe.getUnsafe().putByte(frame + 4, (byte) client.getServerQwpVersion());
+            // FLAG_DEFER_COMMIT: the catch-up carries dictionary entries but NO
+            // rows, so it must never trigger a server-side commit. Today it is
+            // always the first frame on a fresh (empty-transaction) connection, so
+            // committing nothing is a no-op -- but that invariant is load-bearing
+            // and unasserted. Deferring the (empty) commit removes the dependency:
+            // a future mid-stream catch-up cannot prematurely commit an in-flight
+            // deferred transaction. The dictionary delta still registers (as any
+            // deferred data frame's does); only the row commit is deferred, and the
+            // next real frame commits it.
             Unsafe.getUnsafe().putByte(frame + QwpConstants.HEADER_OFFSET_FLAGS,
-                    (byte) (QwpConstants.FLAG_GORILLA | QwpConstants.FLAG_DELTA_SYMBOL_DICT));
+                    (byte) (QwpConstants.FLAG_GORILLA | QwpConstants.FLAG_DELTA_SYMBOL_DICT
+                            | QwpConstants.FLAG_DEFER_COMMIT));
             Unsafe.getUnsafe().putShort(frame + 6, (short) 0); // tableCount
             Unsafe.getUnsafe().putInt(frame + 8, payloadLen);
             long q = writeVarintAt(frame + QwpConstants.HEADER_SIZE, deltaStart);

core/src/test/java/io/questdb/client/test/cutlass/qwp/client/DeltaDictCatchUpTest.java

@@ -92,6 +92,9 @@ public void testReconnectCatchUpRebuildsDictionary() throws Exception {
                 List<String> conn2 = handler.dictFor(2);
                 Assert.assertTrue("2nd connection saw a catch-up frame with 0 tables",
                         handler.sawZeroTableFrameOnConn2);
+                Assert.assertTrue("the catch-up frame carries no rows, so it must defer its "
+                                + "(empty) commit -- FLAG_DEFER_COMMIT set",
+                        handler.catchUpDeferredOnConn2);
                 Assert.assertEquals("2nd connection dictionary size", 2, conn2.size());
                 Assert.assertEquals("alpha", conn2.get(0));
                 Assert.assertEquals("beta", conn2.get(1));
@@ -326,6 +329,9 @@ private static class CatchUpHandler implements TestWebSocketServer.WebSocketServ
         // (rather than a fixed sleep) before sending batch 2, so batch 2 cannot
         // race into connection 1's pre-close window and must land on the reconnect.
         volatile boolean conn1Closed;
+        // Set from the flags byte of the zero-table catch-up frame on connection 2:
+        // the catch-up carries no rows and must defer its (empty) commit.
+        volatile boolean catchUpDeferredOnConn2;
         volatile boolean sawZeroTableFrameOnConn2;
         private final List<List<String>> dictsByConn = new CopyOnWriteArrayList<>();
         private TestWebSocketServer.ClientHandler currentClient;
@@ -352,6 +358,8 @@ public synchronized void onBinaryMessage(TestWebSocketServer.ClientHandler clien
             accumulate(data, dict);
             if (connNumber == 2 && tableCount(data) == 0) {
                 sawZeroTableFrameOnConn2 = true;
+                // FLAG_DEFER_COMMIT is bit 0x01 of the flags byte (offset 5).
+                catchUpDeferredOnConn2 = (data[5] & 0x01) != 0;
             }
             try {
                 client.sendBinary(buildAck(nextSeq.getAndIncrement()));