Document split-flush and dict-getter contracts

Two documentation-only additions to the QWP store-and-forward client,
making previously implicit contracts explicit. No behavior change.

flushPendingRowsSplit: add a "Not atomic across frames" note. A
sealAndSwapBuffer() failure on split frame k>1 leaves frames 1..k-1
published as deferred; the throw skips the trailing table-buffer reset,
so the next flush re-emits the whole batch and the eventual commit
commits the already-published prefix twice. This is pre-existing and
within store-and-forward's at-least-once contract (absorbed by a DEDUP
table or a durable-ack await); the note names the atomic-split fix
(roll back or skip the published prefix on retry) as the larger
follow-up.

PersistedSymbolDict: mark loadedEntriesAddr(), loadedEntriesLen() and
readLoadedSymbols() as construction-phase only. They read the native
entry region that close() frees and nulls, with no closed-guard, so
they are safe only before the slot's I/O thread and any producer append
start; reading them from a running thread would risk a use-after-free.

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

@@ -3526,6 +3526,22 @@ private void flushPendingRows(boolean deferCommit) {
      * own message. All messages except the last carry FLAG_DEFER_COMMIT
      * so the server appends rows without committing until the final
      * message arrives.
+     * <p>
+     * <b>Not atomic across frames.</b> The frames publish one at a time, so a
+     * publish failure partway through -- {@link #sealAndSwapBuffer()} throwing on
+     * frame k&gt;1, e.g. a backpressure deadline or the buffer-recycle timeout --
+     * leaves frames 1..k-1 already on the ring as deferred (appended, not yet
+     * committed). The throw propagates past the {@code resetTableBuffersAfterFlush}
+     * at the end of the loop, so the source rows survive in their table buffers
+     * and the NEXT flush re-emits the whole batch; the eventual commit then
+     * commits the already-published prefix alongside the re-sent copies,
+     * delivering those rows at-least-once (duplicated), not exactly-once. This is
+     * within store-and-forward's at-least-once contract -- a DEDUP table or a
+     * durable-ack await absorbs the duplicate, and the symbol-dict state stays
+     * consistent on the retry (the re-sent frames carry empty deltas and the
+     * write-ahead persist is a {@code pd.size()} no-op). Making the split atomic
+     * (rolling back the published prefix, or skipping it on retry) would be a
+     * larger change.
      *
      * @param deferCommit when true, ALL messages (including the last)
      *                    carry FLAG_DEFER_COMMIT. When false, only the

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

@@ -354,13 +354,22 @@ public synchronized void close() {
      * Base address of the loaded entry region -- the concatenated
      * {@code [len][utf8]} bytes of every recovered symbol in id order, exactly
      * as a delta section carries them. Zero when nothing was recovered.
+     * <p>
+     * <b>Construction-phase only.</b> This hands out a raw pointer into native
+     * memory that {@link #close()} frees and nulls, with no closed-guard and no
+     * synchronization. It is safe to read only BEFORE the slot's I/O thread and
+     * any producer append start -- i.e. while the send loop is being constructed
+     * or an orphan-drain is seeding its mirror, both of which happen-before those
+     * threads. A caller that reads it from a running thread races {@code close()}
+     * and can dereference freed memory (use-after-free).
      */
     public long loadedEntriesAddr() {
         return loadedEntriesAddr;
     }
 
     /**
-     * Byte length of {@link #loadedEntriesAddr()}.
+     * Byte length of {@link #loadedEntriesAddr()}. Construction-phase only, for
+     * the same reason -- see {@link #loadedEntriesAddr()}.
      */
     public int loadedEntriesLen() {
         return loadedEntriesLen;
@@ -371,6 +380,10 @@ public int loadedEntriesLen() {
      * (entry {@code i} is symbol id {@code i}). Used once on recovery to
      * repopulate the producer's global dictionary. Empty when nothing was
      * recovered.
+     * <p>
+     * <b>Construction-phase only</b> -- like {@link #loadedEntriesAddr()}, this
+     * walks the native entry region {@link #close()} frees, with no closed-guard,
+     * so it must run before the I/O thread and any producer append start.
      */
     public ObjList<String> readLoadedSymbols() {
         ObjList<String> out = new ObjList<>(Math.max(size, 1));