test(ha-entity-snapshots): RED tests for load_snapshot restore contract (task 5.1)

Extends persist_load_snapshot's public signature with an
out_entities_restored bool*, per design.md's documented contract. The
static load_snapshot function -- the real restore logic -- is completely
untouched (still today's watermark-only implementation, byte-identical
to before this task); only a thin wrapper was added that naively maps
*out_entities_restored = (rc==0), deliberately scaffolding so the 3 new
RED tests fail for genuine reasons rather than accidentally passing.
ha_handle_snapshot_chunk's sole call site gets a mechanical
declare-and-pass update -- confirmed inert, never reads the new
out-param (task 6.1's job).

Three tests against persist_load_snapshot directly (unlike prior tasks'
tests, which deliberately stayed on the raw-byte-parsing side to avoid
this exact function): restore-before-advance (fails at the job-lookup
assertion -- nothing is ever restored today), corrupted-entity-leaves-
position-unchanged (fails at rc!=0 -- today's code ignores the corrupted
section entirely, since load_snapshot never reads past the legacy
header), legacy-file-reports-position-only (fails at entities_restored==
false -- the naive wrapper claims restoration for every rc==0 case,
including legacy files).

This is the exact function/call site that caused task 2.2's rejection
(a live position-advances-before-restore-validates hazard). Independent
review verified load_snapshot's body is byte-identical to commit
d52eb94, the wrapper does nothing beyond the naive mapping, and ha.c's
change never reads the new out-param anywhere -- no repeat of that
mistake here.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JDYFbrgyDHbvNYcxApKhrX

src/controller/persist.c

@@ -2204,10 +2204,35 @@ static int load_snapshot(persist_t* p, const char* path, uint64_t lsn)
     return 0;
 }
 
-/* Public wrapper for load_snapshot — exposed via persist.h for ha.c (Task 3.5c). */
-int persist_load_snapshot(persist_t *p, const char *path, uint64_t lsn)
+/* Public wrapper for load_snapshot — exposed via persist.h for ha.c (Task 3.5c).
+ *
+ * ha-entity-snapshots task 5.1 (RED, signature-compat stopgap ONLY — task 5.2
+ * owns the real restore-before-advance implementation): `load_snapshot` above
+ * is UNCHANGED, still today's watermark-only behavior (never inspects/restores
+ * any entity payload). This wrapper's *out_entities_restored mapping is
+ * deliberately the most naive one possible — "the underlying call reported
+ * success" — precisely so it does NOT mask the two real gaps task 5.2 must
+ * close: (1) a legacy (position-only) file will report entities_restored=true
+ * here even though it never carried an entity, since load_snapshot() returns
+ * 0 for ANY well-formed header regardless of what (if anything) follows it —
+ * a live instance of the exact false-completeness hazard Requirement 2.4
+ * exists to prevent; (2) a corrupted entity frame is never even inspected —
+ * load_snapshot() returns 0 and already advances p->checkpoint_lsn/
+ * current_lsn before this wrapper is reached, so the "position unchanged on
+ * failure" contract (Requirement 2.3) does not hold yet either. Both are
+ * exactly the behaviors the task 5.1 RED tests assert against. */
+int persist_load_snapshot(persist_t *p, const char *path, uint64_t lsn,
+                          bool *out_entities_restored)
 {
-    return load_snapshot(p, path, lsn);
+    int rc = load_snapshot(p, path, lsn);
+
+    /* Contract: only set on rc==0 (design.md "load_snapshot (extended)" —
+     * "*out_entities_restored is only set when rc==0"); left untouched
+     * otherwise so a failed call never overwrites a caller's own state. */
+    if (rc == 0 && out_entities_restored != NULL)
+        *out_entities_restored = true;
+
+    return rc;
 }
 
 /* P2-2: Standby WAL replay — apply a single replicated entry to in-memory state.