feat(raft-sim-conformance): raft_sim_run + deterministic replay (task 4.4)

src/lib/raft/raft.h

@@ -954,6 +954,23 @@ int raft_sim_restart_node(raft_sim_cluster_t *c, int node_idx);
  */
 int raft_sim_step(raft_sim_cluster_t *c);
 
+/*
+ * raft_sim_run: drive up to `max_steps` raft_sim_step actions through the library
+ * (raft-sim-conformance task 4.4; Req 1.5, 1.6, 5.3).
+ *
+ * Loops raft_sim_step. On the FIRST step that reports an invariant violation
+ * (returns < 0), STOPS immediately and returns that same < 0 value (the step
+ * already dumped the replayable trace to stderr) — the "halt on first violation"
+ * contract (Req 3.5/5.3). If all `max_steps` complete with no violation, returns 0.
+ *
+ * Determinism: every nondeterministic choice flows from c->prng (seeded from
+ * c->seed in raft_sim_conformance_init), so two clusters initialized with the same
+ * (n, election_timeout, seed) and run for the same `max_steps` reach byte-identical
+ * observable state and an identical recorded trace — deterministic replay (Req 1.6).
+ * No wall-clock, address, or uninitialized input ever feeds a choice (Req 1.5).
+ */
+int raft_sim_run(raft_sim_cluster_t *c, int max_steps);
+
 #endif /* XCE_TESTING */
 
 #endif /* RAFT_H */

src/lib/raft/raft_sim.c

@@ -1249,4 +1249,23 @@ int raft_sim_step(raft_sim_cluster_t *c)
     return 0;
 }
 
+/* ---------- multi-step run driver (raft-sim-conformance task 4.4) ---------- */
+
+int raft_sim_run(raft_sim_cluster_t *c, int max_steps)
+{
+    /* Bounded loop of single steps. raft_sim_step is the SOLE consumer of c->prng,
+     * so a run is a pure deterministic function of (n, seed) and the step count —
+     * two same-keyed clusters produce identical traces and final state (R1.5/1.6/
+     * 5.3). Halt on the FIRST violation: raft_sim_step returns < 0 and has already
+     * dumped the replayable trace, so propagate that value unchanged (R3.5). A clean
+     * exhaustion of the step budget returns 0. */
+    for (int step = 0; step < max_steps; step++) {
+        int rc = raft_sim_step(c);
+        if (rc < 0)
+            return rc; /* first invariant violation — stop and surface it */
+    }
+
+    return 0;
+}
+
 #endif /* XCE_TESTING */