fix(qwp): guard header reads in recovery; drop the sparse-tail-only WARN framing

M1: openExisting reads magic/version/baseSeq before scanFrames with no guard,
so an unbacked page 0 (unflushed header on a truncate-based-allocate FS after a
crash, or a file truncated under the mapping) faults with an InternalError that
SegmentRing's per-file catch (MmapSegmentException) does not catch -- it escapes
to the outer catch (Throwable) and aborts recovery of every sibling segment.
Convert an isMmapAccessFault into a MmapSegmentException in openExisting's catch
so only that one .sfa is skipped. Adds a portable regression test.

M2: the scanFrames in-mapping-fault WARN framed the outcome as "Expected when a
prior session left a sparse segment tail", downplaying a possible mid-file media
error. Reword it to state frames beyond the fault are discarded and that a bad
sector is indistinguishable here, and document that tornTailBytes() reports 0
for an unbacked bail-out region by design.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: puzpuzpuz

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

@@ -310,6 +310,23 @@ public static MmapSegment openExisting(String path) {
                 Files.munmap(addr, fileSize, MemoryTag.MMAP_DEFAULT);
             }
             Files.close(fd);
+            // The header reads above (magic/version/baseSeq) run before
+            // scanFrames and are otherwise unguarded. An unbacked page 0 --
+            // an unflushed header on a truncate-based-allocate filesystem
+            // after a crash (create() does not msync), or a file truncated
+            // under the mapping -- faults at the Unsafe intrinsic site as a
+            // catchable InternalError. Convert it to a MmapSegmentException so
+            // SegmentRing's per-file catch skips just this .sfa, instead of
+            // letting the raw InternalError escape to SegmentRing's outer catch
+            // and abort recovery of every sibling segment. scanFrames and
+            // detectTornTail already handle their own in-mapping faults; this
+            // covers the header block and any future reader placed ahead of the
+            // scan.
+            if (isMmapAccessFault(t)) {
+                throw new MmapSegmentException(
+                        "unreadable mapped header page in " + path
+                                + " (unbacked/sparse page 0): " + t.getMessage(), t);
+            }
             throw t;
         }
     }
@@ -502,6 +519,13 @@ public long frameCount() {
      * fresh segments, memory-backed segments, and cleanly partially-filled
      * recovered segments. Operators / tests can read this to tell silent
      * truncation (corruption) from a normal partial fill (no incident).
+     * <p>
+     * One case this does NOT count: when the scan stops because the bail-out
+     * region is itself an unbacked mapped page (an in-mapping fault, not a
+     * backed torn header), that region cannot be probed, so this returns
+     * {@code 0} even though frames may have been discarded. That outcome is
+     * surfaced by the {@code WARN} in {@link #scanFrames} instead -- see it for
+     * the benign-tail-vs-media-error caveat.
      */
     public long tornTailBytes() {
         return tornTailBytes;
@@ -595,8 +619,12 @@ private static long scanFrames(long addr, long fileSize) {
                 throw e;
             }
             LOG.warn("SF segment recovery: unreadable mapped page at offset {} (file size {}); "
-                            + "treating it as the end of recoverable data. Expected when a prior "
-                            + "session left a sparse segment tail; investigate disk health if it recurs.",
+                            + "treating it as the end of recoverable data -- any frames beyond this "
+                            + "offset are discarded. The usual cause is a benign sparse pre-allocation "
+                            + "tail (e.g. a truncate-based allocate on ZFS) left by a prior session, "
+                            + "but a mid-file media error (bad sector) is indistinguishable here; "
+                            + "check disk health if this segment was expected to be fully written or "
+                            + "if this recurs.",
                     pos, fileSize);
         }
         return pos;

core/src/test/java/io/questdb/client/test/cutlass/qwp/client/sf/cursor/MmapSegmentRecoveryFaultTest.java

@@ -25,6 +25,7 @@
 package io.questdb.client.test.cutlass.qwp.client.sf.cursor;
 
 import io.questdb.client.cutlass.qwp.client.sf.cursor.MmapSegment;
+import io.questdb.client.cutlass.qwp.client.sf.cursor.MmapSegmentException;
 import io.questdb.client.std.Files;
 import io.questdb.client.std.MemoryTag;
 import io.questdb.client.std.Unsafe;
@@ -37,6 +38,7 @@
 
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.fail;
 
 /**
  * Regression guard for the recovery-time SIGBUS hazard in {@link MmapSegment}.
@@ -176,6 +178,37 @@ public void testRecoverySurvivesPayloadReachingUnbackedPage() throws Exception {
         });
     }
 
+    /**
+     * M1 regression: the header block (magic/version/baseSeq) is read before
+     * {@code scanFrames}, so an unbacked page 0 faults ahead of the guarded
+     * scan. {@link MmapSegment#openExisting} must surface that as a
+     * {@link MmapSegmentException} -- the per-file signal {@code SegmentRing}
+     * catches to skip just this {@code .sfa} -- and never let the raw
+     * {@code InternalError} escape and abort recovery of every sibling segment.
+     * <p>
+     * Portable across filesystems: on a hole-faulting FS (ZFS) the fault is
+     * converted to a {@code MmapSegmentException} in {@code openExisting}'s
+     * catch; on a hole-zero-filling FS (ext4) page 0 reads back as zeroes, so
+     * the magic check fails and throws {@code MmapSegmentException} directly.
+     * Either way the file is skippable, not fatal.
+     */
+    @Test
+    public void testUnbackedHeaderPageIsSkippableNotFatal() throws Exception {
+        TestUtils.assertMemoryLeak(() -> {
+            final String path = tmpDir + "/seg-unbacked-header.sfa";
+            writeSegment(path, 3L, new int[]{64});
+            // Punch the whole file into a hole -- page 0 (the header) included.
+            punchSparseTail(path, 0L);
+            try {
+                MmapSegment.openExisting(path).close();
+                fail("expected MmapSegmentException for an unbacked header page");
+            } catch (MmapSegmentException expected) {
+                // ok -- SegmentRing's per-file catch skips just this file
+                // instead of aborting recovery of the whole slot.
+            }
+        });
+    }
+
     /**
      * Creates a segment at {@code path} and appends one frame per entry in
      * {@code payloadLens} (each filled with non-zero bytes so recovery can tell