feat(ha-commit-durability): add XCE_TESTING durable-LSN-on-disk verification seam (task 1.2)

src/include/persist.h

@@ -184,6 +184,35 @@ int persist_commit_barrier(persist_t* p, uint32_t timeout_ms);
 /* Force WAL fdatasync (for tests and clean shutdown) */
 int persist_flush(persist_t* p);
 
+#ifdef XCE_TESTING
+/* ============================================================
+ * Durability-verification test seam (ha-commit-durability Req 3.2, 3.3)
+ *
+ * persist_test_durable_lsn_on_disk — re-read and CRC-validate the WAL
+ * segments from STABLE STORAGE and return the highest fully-persisted
+ * LSN, independent of the in-memory current_lsn / committed_lsn
+ * watermarks.  Lets a test assert that an acknowledged operation is
+ * recoverable from disk after an immediate, ungraceful termination —
+ * without relying on the background flush timer (Req 3.2):
+ *
+ *     persist_wal_async(p, ...);     // append to page cache
+ *     persist_flush(p);              // fdatasync → durable on disk
+ *     lsn = persist_test_durable_lsn_on_disk(p);  // highest durable LSN
+ *
+ * It scans the same on-disk format and CRC chain as recovery, stopping
+ * at the first corruption / short read / pre-allocated zero region, so
+ * it reports only entries that are genuinely on stable storage.  It
+ * never mutates persist_t state and fires no hooks (Req 3.3 — the seam
+ * is purely inspective; the acknowledgment contract is unchanged).
+ *
+ * Returns the highest durable LSN, or 0 when nothing is durable (empty
+ * first-boot WAL, no segments).  Compiled out of production builds:
+ * the xce_controller target is built without -DXCE_TESTING and links
+ * without this symbol.
+ * ============================================================ */
+uint64_t persist_test_durable_lsn_on_disk(persist_t* p);
+#endif /* XCE_TESTING */
+
 /* Checkpoint */
 int persist_checkpoint(persist_t* p);