myxce/.kiro/specs/raft-sim-conformance/spec.json

{
  "feature_name": "raft-sim-conformance",
  "created_at": "2026-06-21T13:00:00Z",
  "updated_at": "2026-06-21T13:00:00Z",
  "language": "en",
  "phase": "implementation-complete",
  "approvals": {
    "requirements": {
      "generated": true,
      "approved": true
    },
    "design": {
      "generated": true,
      "approved": true
    },
    "tasks": {
      "generated": true,
      "approved": true
    }
  },
  "ready_for_implementation": true,
  "note": "Auto-approved (-y mode). Extends src/lib/raft/raft_sim.c into an in-process TLA+ conformance/verification harness driving N library instances through raft.tla Next-action-equivalent transitions (Restart, Timeout, RequestVote, BecomeLeader, ClientRequest, AppendEntries, AdvanceCommitIndex, Receive incl. UpdateTerm + DropStaleResponse, DuplicateMessage, DropMessage) and asserting the four Raft safety invariants (Election Safety, Log Matching, Leader Completeness, State Machine Safety) every step. Seedable/deterministic driver; randomized + targeted scenarios (partitions, restarts, drop/dup/reorder, Figure-8); failure-trace reproduction; CI-runnable target; deliberately-broken-build negative test reproducing a bug-851-class divergence. Boundary: owns src/lib/raft/raft_sim.c + harness/test files ONLY; does NOT modify the protocol implementation (raft.c/raft.h protocol semantics) — it consumes the raft-log-replication + raft-commit-safety entry points/callbacks verbatim. Depends: raft-log-replication, raft-commit-safety.",
  "updated_at_tasks": "2026-06-24T16:43:39.427Z",
  "validate_impl": {
    "decision": "GO",
    "validated_at": "2026-07-17T18:00:00Z",
    "note": "First post-implementation validation run -- all 23 tasks (1.1-8.1) were already [x] with no prior validate_impl record and spec.json's phase field had never advanced past tasks-generated despite implementation being complete. Full `/xce-build lib` ASAN run: clean compile, 293/293 Unity tests PASS (0 Fail, 0 Ignored), meson 'libxce test' target 1/1 OK in 36.11s, zero AddressSanitizer/LeakSanitizer/UBSan findings anywhere in the log. Every raft-sim conformance test observed by name and PASS: all 4 invariant-checker unit tests (election safety, log matching, leader completeness, state machine safety) both directions, raft_sim_check_all first-failure composition, the 5 targeted scenarios (partition/heal, restart-churn, drop/dup/reorder, Figure-8, stale-rejoin/G5), the M-seed randomized sweep (test_sim_6_1_seed_sweep), the deliberately-broken-build negative test asserting both directions (test_sim_7_2_negative_both_directions), and the optional TLC trace-export test (task 8.1, gated off by default). Boundary audit: grepped every commit subject-tagged feat|test|fix|docs(raft-sim-conformance) across full git history -- touched files are exactly raft.h, raft_sim.c, test_raft.c (+ this spec's own docs); zero raft.c protocol edits, zero controller files. Harness confirmed allocation-free (no malloc/calloc/realloc/free in raft_sim.c), matching the design's ASAN-clean-by-construction claim. Requirements coverage: all 8 requirement sections (1-8, 34 acceptance criteria) map to committed tasks and passing tests; no gaps. Design alignment: File Structure Plan matches actual (raft.h XCE_TESTING-section-only, raft_sim.c, test_raft.c); component graph (message bag, in-memory adapter, seeded scheduler, 4 checkers, trace recorder, scenario drivers, fault switch) all present and named as designed. Cross-task integration: task 4.2's Implementation Notes record an UPSTREAM raft.c defect (bug-1095/1096, Election Safety violation from a non-idempotent vote-reply tally + missing stale-term drop) surfaced by the oracle itself -- correctly reported out-of-boundary rather than masked, and subsequently fixed upstream in raft.c (commit b5b7e01, verified live at raft_on_vote_reply: per-peer vote_replies[] dedup + term<s->term drop), after which downstream tasks 5.x/6.1/7.2 assert zero violations on the correct build as required. This validation pass also corrected buglog.json's bug-1095 entry, which was stale (said 'NOT FIXED' although the fix has been live since 2026-06-24 per bug-1096 and tasks.md's own notes).",
    "known_limitations": [
      "tasks.md task 7.1 describes the negative-test mechanism as a 'compile-time fault switch,' but the shipped implementation (and design.md, corrected in commit ffeb7c2) is a runtime bitflag (cluster.fault_inject / RAFT_SIM_BREAK_TERM_STAMP|TRUNCATE set via raft_sim_set_fault_inject) so both the broken and correct configurations can be asserted within a single test binary per R7.4. Wording drift only in tasks.md's task header; behavior is correct, intentional, and matches design.md.",
      "design.md's invariant-checker narrative does not reflect the leader-only commit model correction recorded in tasks.md's own Implementation Notes for tasks 5.1/5.2: a FOLLOWER never advances commit_index/applied[] from AppendEntries (raft_on_append_entries_request does (void)leader_commit -- intended XCE design, follower commit visibility is a controller/heartbeat concern owned by ha-heartbeat-committed-propagation, not this library). Scenario tests correctly assert leader-side commit_index and log convergence rather than follower commit_index equality; design.md's prose was not back-ported to state this explicitly. Documentation-drift note only.",
      "raft.h's XCE_TESTING sim section is also extended by a later, adjacent spec (raft-apply-decoupling, commit 5f98d1b, test_sim_apply_decoupling_* tests) building on this harness's scheduler/checkers. This is expected downstream consumption, not a boundary violation of this spec, but a future change to raft-sim-conformance's scheduler/action-record shape should check that spec's tests too."
    ]
  }
}