feat(ha-commit-durability): WAL recovery integrity verdict (CLEAN/TRUNCATED) + recovery_truncated flag (task 3.1)

src/include/persist.h

@@ -2,6 +2,7 @@
 #include <pthread.h>
 #include <stdarg.h>
 #include <stdatomic.h>
+#include <stdbool.h>
 #include <stddef.h>
 #include <stdint.h>
 
@@ -12,6 +13,28 @@
 /* Forward declaration */
 typedef struct cluster_s cluster_t;
 
+/* ============================================================
+ * Recovery-integrity verdict (ha-commit-durability task 3.1, Req 2.1)
+ *
+ * The outcome of WAL replay at startup, distinguishing a structurally
+ * intact log from one whose chain is broken. It is about the STRUCTURE
+ * of the local log, NOT about being behind the cluster: a clean log that
+ * simply ends below the cluster's committed high-water mark is still
+ * RECOVER_CLEAN (the freshness/promotion fence handles "behind"). A
+ * corruption-truncated recovery is NEVER reported as a clean recovery.
+ * ============================================================ */
+typedef enum {
+    RECOVER_CLEAN     = 0, /* WAL forms a valid CRC chain to a clean entry
+                            * boundary: clean EOF, pre-allocated-zero tail,
+                            * snapshot-sentinel + clean replay, or an empty
+                            * first-boot WAL (no entries != corruption). */
+    RECOVER_TRUNCATED = 1, /* replay stopped on structural corruption: a CRC
+                            * chain break, a CRC mismatch, or a short/partial
+                            * entry read — the log cannot be reconstructed
+                            * contiguously. Marks the member non-promotable
+                            * (consumed by the promotion gate, task 4.3). */
+} recover_verdict_t;
+
 /* ============================================================
  * Persistence configuration (Part 2.6)
  * ============================================================ */
@@ -97,6 +120,22 @@ struct persist_s {
     uint64_t        total_wal_bytes;
     char            seg_path[4096];
 
+    /* Recovery-integrity verdict (ha-commit-durability task 3.1, Req 2.1).
+     * Set by persist_recover/replay_wal at startup: RECOVER_CLEAN when the
+     * local WAL forms a valid CRC chain to a clean entry boundary (incl. an
+     * empty first-boot WAL, a snapshot-sentinel + clean replay, and a
+     * pre-allocated-zero tail), RECOVER_TRUNCATED when replay stopped on a
+     * structural corruption — a CRC chain break, a CRC mismatch, or a
+     * short/partial entry read — so the on-disk log cannot be reconstructed
+     * contiguously. A node that cleanly ends BELOW the cluster high-water is
+     * still CLEAN here (the freshness/promotion fence catches "behind", task
+     * 4.2/4.3 — not this verdict). 3.1 only CLASSIFIES + sets this; it does
+     * NOT FATAL (task 3.3) and does NOT fence promotion (task 4.3, which
+     * CONSUMES this verdict). Defaults to RECOVER_CLEAN before recovery runs
+     * (a fresh store is clean). Written single-threaded during recovery
+     * before the node participates; read by the promotion gate thereafter. */
+    recover_verdict_t recovery_verdict;
+
     /* Paths (derived from workdir + name via persist_set_workdir) */
     char            wal_path[4096];
     char            snap_path[4096];
@@ -227,6 +266,16 @@ int persist_flush(persist_t* p);
  * any thread. Returns 0 when nothing is yet durable. */
 uint64_t persist_durable_lsn(persist_t* p);
 
+/* Recovery-integrity verdict + flag (ha-commit-durability task 3.1, Req 2.1).
+ * persist_recovery_verdict returns the RECOVER_CLEAN / RECOVER_TRUNCATED
+ * verdict computed by the last persist_recover (RECOVER_CLEAN on a fresh
+ * store before recovery runs). persist_recovery_truncated is the convenience
+ * flag form (true iff the verdict is RECOVER_TRUNCATED) the promotion gate
+ * (task 4.3) consumes to mark the member non-promotable. Both are pure reads
+ * of recovery state established single-threaded at startup. */
+recover_verdict_t persist_recovery_verdict(persist_t* p);
+bool persist_recovery_truncated(persist_t* p);
+
 /* Register a durable-advance wake callback (ha-commit-durability task 2.2).
  * The group-commit flusher calls fn(ctx) after it advances durable_lsn and
  * after releasing p->lock, so a consumer (the commit engine) can re-evaluate