feat(ha-term-safety): on_persist_entry callback body (task 2.1)

Replaces the iter-1 stub: persist_set_term(p, term) stamps the leader/library term
into hdr.term, then role-routes the write — primary via persist_wal_async, standby
via persist_wal_write_replicated(p, index, ...). Persist failure returns non-zero
(no false ACK; durable_lsn unchanged); bug-850 contiguity guard + persist-before-ACK
preserved beneath. In-flight raft_entry_blob_t {type,payload_len} envelope added to
wal_types.h (never enters the 40-byte header). 3 tests, reviewer APPROVED.

Deferred (recorded in tasks.md): task 3.1 must retire the hand-rolled primary append
so current_lsn tracks the library index; task 3.2 must not call on_persist_entry on
heartbeats. Per-group 0 failures (pre-existing test_commit_barrier_reply leak aside).

src/include/wal_types.h

@@ -23,6 +23,27 @@ typedef struct {
     uint32_t status; /* xce_queue status flags after this transition */
 } wal_queuehdr_t;
 
+/* ── Raft adapter entry-blob envelope (ha-term-safety task 2.1) ─────────────
+ * The raft library (src/lib/raft/raft.c) holds NO entry bytes: it carries one
+ * opaque (entry, len) blob through raft_log_append / on_persist_entry, leaving
+ * its encoding entirely to the controller adapter. This struct IS that
+ * encoding: a fixed 8-byte prefix recording the WAL entry `type` and the
+ * `payload_len` of the bytes that immediately follow it, so on_persist_entry
+ * can recover (type, payload, len) for the existing persist write path.
+ *
+ * This is purely an in-flight wire/blob format between the library callback
+ * and persist.c — it is NEVER written to the WAL header (that stays the 40-byte
+ * wal_entry_hdr_t, R1.7); only the decoded `type` + `payload` reach the WAL.
+ *
+ * The append/replication driver (tasks 3.1/3.2) packs this same prefix before
+ * the payload when calling raft_log_append / routing an AppendEntries, so the
+ * encoder and decoder share one definition (no drift). */
+typedef struct {
+    uint32_t type;        /* wal_entry_type enum value for this entry */
+    uint32_t payload_len; /* bytes of payload immediately following this header */
+    /* uint8_t payload[payload_len] follows */
+} raft_entry_blob_t;
+
 /* ============================================================
  * WAL entry header — 40 bytes, 8-byte aligned (Part 2.2)
  * ============================================================ */