test(ha-convergence-recovery): RED quorum transition logging tests + seam (task 5.1)

src/controller/ha.h

@@ -211,6 +211,15 @@ typedef struct {
                                          * Slot identity (the repl registry slot
                                          * index) is stable across schedule/run.
                                          * 0 at init (cleared by ha_init memset). */
+    /* ── New field added by ha-convergence-recovery spec (Task 5.x) ──────── */
+    _Atomic int      quorum_lost;       /* Quorum-transition edge detector (Req
+                                         * 8.1-8.3): 0 = quorum held (or unknown
+                                         * at init), 1 = quorum lost.  Flipped by
+                                         * ha_log_quorum_transition via CAS so the
+                                         * loss/restore WARN is emitted exactly
+                                         * once per edge (no log storms across
+                                         * repeated dispatch-gate rejections).
+                                         * 0 at init (cleared by ha_init memset). */
 } ha_state_t;
 
 /* ── Public API ────────────────────────────────────────────── */
@@ -377,6 +386,35 @@ void cluster_apply_ctrlhello_reply(cluster_t *c, uint64_t committed_lsn,
  */
 int ha_walack_on_ack(cluster_t *c, void *ep, int peer_idx, uint64_t acked_lsn);
 
+/*
+ * ha_log_quorum_transition: emit an operator-visible WARN on each write-quorum
+ * loss/restore EDGE (ha-convergence-recovery task 5.x, Req 8.1, 8.2, 8.3).
+ *
+ * Evaluates the current write-quorum state and compares it against the
+ * ha_state_t.quorum_lost edge-detector flag.  On a TRANSITION (and only on a
+ * transition), it atomically flips the flag via CAS and emits exactly one WARN:
+ *   - loss:    "HA quorum lost: connected=%d required=%d"     (Req 8.1)
+ *   - restore: "HA quorum restored: connected=%d required=%d" (Req 8.2)
+ * The flag makes the logging an edge detector, NOT a latch: repeated calls while
+ * the state is unchanged emit nothing (Req 8.3 — no log storms across repeated
+ * dispatch-gate rejections), but a later loss/restore cycle logs again.  The CAS
+ * guarantees once-per-transition under concurrency.
+ *
+ * Call sites (task 5.2): the standby_endpoints mutation points (promotion
+ * registration, RDHUP removal, on_standby_connected) plus the ha_dispatch_gate
+ * quorum-rejection branch as a backstop.  Observability only — never gates an
+ * operation outcome.
+ *
+ * Defined in ha_convergence.c (a unit-linkable TU) so the quorum-transition
+ * tests can drive it directly against a real persist/repl fixture.
+ *
+ * RED scaffold (task 5.1): the current definition is a NO-OP — it performs no
+ * edge detection, flips no flag, and emits no WARN — so the quorum-transition
+ * tests FAIL until task 5.2 lands the real edge-detection logic and wires the
+ * call sites.
+ */
+void ha_log_quorum_transition(ha_state_t *ha);
+
 
 /* ── Redirect helpers used by join.c ──────────────────────── */
 
@@ -986,6 +1024,30 @@ void raft_cb_become_follower_with_cluster_for_test(cluster_t *c, uint64_t term);
  */
 int ha_walack_continuation_for_test(cluster_t *c, void *ep, int peer_idx,
                                     uint64_t acked_lsn);
+
+/*
+ * ha_quorum_transition_log_hook: test-only emission-count seam for
+ * ha_log_quorum_transition (ha-convergence-recovery task 5.x, Req 8.1-8.3).
+ *
+ * There is NO log-capture harness in this testsuite, so the quorum-transition
+ * tests use a counter/edge-observable instead (the task permits "log-capture OR
+ * counter-hook pattern").  When non-NULL, ha_log_quorum_transition invokes this
+ * hook EXACTLY ONCE on each transition it WARNs about, passing the new state and
+ * the connected/required counts that go into the WARN line.  Tests count
+ * invocations to assert "logged once per transition" (Req 8.3) and inspect the
+ * arguments to assert the loss line carries the right counts (Req 8.1).
+ *
+ * Signature: void hook(int lost, int connected, int required)
+ *   lost      — 1 on a quorum-LOSS edge, 0 on a quorum-RESTORE edge.
+ *   connected — connected standby count reported in the WARN line.
+ *   required  — required standby count (quorum threshold) in the WARN line.
+ *
+ * RED scaffold (task 5.1): ha_log_quorum_transition is a no-op stub that never
+ * invokes this hook, so the transition tests' emission-count assertions FAIL
+ * until task 5.2 implements the real edge detection.
+ */
+extern void (*ha_quorum_transition_log_hook)(int lost, int connected,
+                                             int required);
 #endif
 
 #endif /* HA_H */