docs(qwp): state the recovery no-mutation guarantee exactly as strong as it is

Two in-diff comments claimed more than the code proves.

The recovery-scan comment asserted 'a failed recovery never mutates the
slot (single exception: ...sanitizeSealedResidue)'. There are more
windows where a recovery that later fails has already durably mutated:
the legacy-migration sanitize zeroes residue before SfManifest.create
(or any later step) can fail, and validated-extra cleanup plus
corrupt-file quarantine run before the active-sanitize barrier or ring
construction can fail. Restate the invariant as what the code actually
guarantees -- a failed recovery never mutates COMMITTED CHAIN BYTES --
and enumerate the windows, each confined to proven-dead zeroes or
preserve-by-rename quarantines.

The db8938e-derived javadoc claimed sanitizeTornTail runs 'only on
residue that validation proves non-load-bearing', gliding over the
resumed active with '(reclaimed by appends anyway)'. No such proof
exists for the active -- it has no successor to bound its accounting,
and past a mid-file tear its residue can hold valid-CRC frames of real
unacked payloads. Zeroing them is a deliberate POLICY (replay cannot
cross the tear; unzeroed residue risks the reseal-brick and stale-frame
resurrection hazards), not a validation-derived proof. Say so at every
site that carried the stronger wording: openExisting's javadoc, the
scan-time observe-only comment, sanitizeTornTail's contract, and the
active-sanitize call site in SegmentRing.

Comments only; no behavior change.

Author: bluestreak01

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

@@ -299,11 +299,16 @@ public static MmapSegment createInMemory(long baseSeq, long sizeBytes) {
      * still hold unreachable frames with valid CRCs -- the only surviving copy
      * of real payloads -- so whether it may be destroyed is a chain-level
      * decision this method cannot make. {@link SegmentRing} recovery invokes
-     * {@link #sanitizeTornTail()} only once the chain has fully validated and
-     * only on residue that validation proves non-load-bearing (the resumed
-     * active's tail, which appends are about to reclaim anyway, and sealed
-     * suffixes whose frame accounting is proven complete); every fail-closed
-     * path leaves the bytes intact on disk for operator extraction. Clean
+     * {@link #sanitizeTornTail()} only once the chain has fully validated,
+     * and the justification differs by role: sealed suffixes are zeroed on
+     * PROOF (frame accounting validated complete, so the residue can hold no
+     * replayable frame -- a tear that cost frames fails closed instead, with
+     * every byte left on disk for operator extraction), while the resumed
+     * active's tail is zeroed by POLICY -- past a mid-file tear it can still
+     * hold valid-CRC frames of real unacked payloads, but they are
+     * unreachable by replay (the FSN sequence breaks at the tear) and
+     * leaving them risks the reseal-brick and stale-frame-resurrection
+     * hazards. Clean
      * partial fills (writer never attempted to write past the last valid
      * frame) do not log and report {@code 0}.
      */
@@ -375,13 +380,17 @@ public static MmapSegment openExisting(FilesFacade ff, String path) {
                 // Observe-only: report the residue, never touch it here. A
                 // torn tail may be an interrupted append (dead bytes) OR a
                 // mid-file tear with unreachable valid-CRC frames past it --
-                // the only surviving copy of real payloads. Only chain-level
-                // validation can tell the two apart, so the destroy/preserve
-                // decision belongs to SegmentRing.recover: it invokes
-                // sanitizeTornTail on the segment it resumes as active (and
-                // on proven-dead sealed suffixes) AFTER the chain proves the
-                // residue is not load-bearing, and fails closed with every
-                // byte left on disk in all other cases.
+                // the only surviving copy of real payloads. The
+                // destroy/preserve decision belongs to SegmentRing.recover.
+                // For sealed members chain validation PROVES the residue
+                // dead (complete frame accounting) before sanitizeTornTail
+                // runs, and a tear that cost frames fails closed with every
+                // byte left on disk. For the segment resumed as active no
+                // such proof exists (there is no successor to bound it): its
+                // residue is zeroed by policy once the rest of the chain
+                // validates, because replay cannot cross the tear and
+                // unzeroed residue risks reseal-brick and stale-frame
+                // resurrection.
                 LOG.warn("SF segment {}: torn tail of {} bytes at offset {} "
                                 + "(file size {}, frames recovered {}). "
                                 + "The residue is preserved pending chain validation. "
@@ -752,9 +761,13 @@ public long tornTailBytes() {
      * {@link #openExisting}: after a mid-file tear the residue can hold
      * unreachable valid-CRC frames that are the only surviving copy of
      * unacked payloads. The caller ({@link SegmentRing} recovery) must first
-     * prove the residue is not load-bearing -- the resumed active's tail
-     * (reclaimed by appends anyway) or a sealed suffix whose frame accounting
-     * validated complete against the chain. Must run before any append
+     * establish the residue is not load-bearing, and the strength of that
+     * claim differs by role: a sealed suffix is PROVEN dead (frame
+     * accounting validated complete against the chain), while the resumed
+     * active's tail past a mid-file tear is discarded by POLICY, not proof
+     * -- it can hold valid-CRC frames of real unacked payloads that are
+     * unreachable by replay (the FSN sequence breaks at the tear), and
+     * leaving them risks the two hazards above. Must run before any append
      * resumes; appending first would put live frames inside the zeroed range,
      * so that ordering is rejected. Idempotent; no-op when no residue was
      * observed. The fsync is load-bearing: in MEMORY durability mode rotation

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

@@ -243,10 +243,18 @@ static Recovery recover(
         // Files whose own bytes prove corruption (bad magic, sub-header size,
         // negative baseSeq). They are excluded from the chain and quarantined
         // to <name>.corrupt — but only AFTER the surviving chain validates (or
-        // resolves to EMPTY), so a failed recovery never mutates the slot
-        // (single exception: proven-dead sealed residue is zeroed just before
-        // the fail-closed first-sight throw in sanitizeSealedResidue -- bytes
-        // the already-validated chain proves no replay can ever need).
+        // resolves to EMPTY). The precise invariant: a failed recovery never
+        // mutates COMMITTED CHAIN BYTES. It is not "never mutates the slot"
+        // -- several windows durably mutate before a later step can still
+        // fail: proven-dead sealed residue is zeroed just before the
+        // fail-closed first-sight throw in sanitizeSealedResidue; the
+        // legacy-migration sanitize zeroes proven-dead residue before
+        // SfManifest.create (or any later step) can fail; and validated-
+        // extra cleanup plus corrupt-file quarantine run before the
+        // active-sanitize barrier or ring construction can fail. Every such
+        // window is confined to bytes the already-validated chain proves no
+        // replay can ever need, or to preserve-by-rename quarantines that
+        // keep the bytes on disk.
         // Whether a quarantined file was load-bearing is decided by the
         // manifest-boundary / contiguity checks below, not by the skip itself.
         // Operational open/stat/read/mmap errors, observed size instability,
@@ -555,7 +563,12 @@ static Recovery recover(
             // where rotation does not sync the sealed predecessor's data
             // pages. A failed barrier aborts recovery (fail closed); the
             // retry re-observes the same residue because openExisting never
-            // mutates.
+            // mutates. Unlike sealed suffixes, the active's residue is NOT
+            // proven dead -- past a mid-file tear it can hold valid-CRC
+            // frames of real unacked payloads. Zeroing is policy: replay
+            // cannot cross the tear, and preserving the bytes would trade
+            // the two hazards above for data no recovery path can use (see
+            // sanitizeTornTail).
             active.sanitizeTornTail();
             for (int i = 1, n = chain.size(); i < n; i++) {
                 chain.get(i - 1).linkSuccessor(chain.get(i));