feat(ha-commit-durability): pre-promotion eligibility gate + catch-up fence/release (task 4.3)

src/controller/ha.h

@@ -497,6 +497,50 @@ void ha_compute_safe_committed_lsn(ha_elect_ctx_t *ctx,
                                     uint64_t       *safe_lsn_out,
                                     uint64_t       *safe_tag_out);
 
+/* ── ha-commit-durability task 4.3: pre-promotion eligibility gate ──────────
+ *
+ * ha_promotion_gate_decision: PURE pre-promotion eligibility decision (Req 2.2,
+ * 2.5, 2.6).  Maps the promoting member's recovery/durability state to the Boot
+ * Policy Decision Table outcome by building recover_policy_inputs_t and
+ * delegating to persist_recover_decision (DRY — the 3.2/3.3 decision table is
+ * the single source of truth; this gate does not re-derive it):
+ *   - recovery_truncated  → the task-3.1 structural-corruption flag.
+ *   - durable_floor       → the local CLAMPED durable position (read AFTER the
+ *                           promotion-path persist_truncate_wal_above so the
+ *                           2.2 truncate-clamp is reflected).
+ *   - safe_hwm            → the cluster committed high-water mark from the voter
+ *                           replies (ha_compute_safe_committed_lsn), NOT a stale
+ *                           ctrlhello.
+ *   - peer_reachable      → a healthy peer is reachable to catch up from.
+ *   - catch_up_succeeded  → catch-up reached a committed-consistent state.
+ * A member is "behind the HWM" iff durable_floor < safe_hwm.  Returns
+ * RECOVER_DECISION_{ELIGIBLE,FENCE,FATAL}; a hollow node (truncated OR behind)
+ * is never ELIGIBLE until it catches up, regardless of quorum size (Req 2.5).
+ */
+recover_decision_t ha_promotion_gate_decision(bool     recovery_truncated,
+                                              uint64_t durable_floor,
+                                              uint64_t safe_hwm,
+                                              bool     peer_reachable,
+                                              bool     catch_up_succeeded);
+
+/* ha_evaluate_promotion_fence: live pre-promotion gate over ha->in_catch_up
+ * (Req 2.2, 2.6).  Evaluates ha_promotion_gate_decision and applies the fence:
+ *   - ELIGIBLE → clears the in_catch_up fence and returns ELIGIBLE (promotion
+ *                may proceed; a member that has caught up past the committed
+ *                boundary regains eligibility — Req 2.6).
+ *   - FENCE    → sets the in_catch_up fence (refuse promotion; catch up from a
+ *                healthy peer) and returns FENCE.
+ *   - FATAL    → routes through persist_recover_fatal_if_unrecoverable (logs the
+ *                truncation boundary at ERROR then terminates; the test seam
+ *                persist_fatal_hook captures it) and returns FATAL.
+ * Reuses the existing in_catch_up fence — does NOT invent a parallel fence. */
+recover_decision_t ha_evaluate_promotion_fence(ha_state_t *ha,
+                                               bool        recovery_truncated,
+                                               uint64_t    durable_floor,
+                                               uint64_t    safe_hwm,
+                                               bool        peer_reachable,
+                                               bool        catch_up_succeeded);
+
 /* ── Task 3.2: Unified replication decision enum and evaluator ────────────── */
 
 /*