wdgzyjx/myxce
1
0
Fork 0
forked from lei.chen/myxce
Code Pull requests Activity
myxce/.kiro/specs/ha-commit-durability/tasks.md

38 KiB
Raw Blame History

Implementation Plan

TDD is mandatory (project rule): write the failing test in testsuite/ before the C change (red → green → refactor). Re-verify HA changes against raft/raft.tla and the src/controller/CLAUDE.md Protocol Verification Checklist. Most core tasks edit the same correctness-critical files (persist.c, commit.c, ha.c, cluster.c) and are therefore sequential by design; only genuinely file-disjoint analysis is marked (P).

  • 1. Foundation: durability verification seam and deterministic reproduction

  • 1.1 Add a configurable flush-cadence override

    • Parse a --wal-sync-ms controller flag (following the existing --sync-timeout-ms convention) into the persistence config before persistence starts; default behavior unchanged.
    • Observable: starting a controller with --wal-sync-ms <N> sets the flush cadence to N; omitting it preserves the current default.
    • Requirements: 3.1
    • Boundary: DurabilityConfig

  • 1.2 Add the test-only durability-verification hook

    • Add an XCE_TESTING-gated seam that lets a test assert an acknowledged operation is recoverable after an immediate ungraceful termination; compiled out of production builds.
    • Observable: in a test build the hook is callable and the production build links without it.
    • Requirements: 3.2, 3.3
    • Boundary: DurabilityTestSeam

  • 1.3 Drive a deterministic durability reproduction from the soak harness

    • Extend test-commit-durability.sh with a deterministic mode that widens the batching window / uses the seam and kills a durable contributor in-window.
    • Observable: on the current (unfixed) build the deterministic mode reports DATA LOSS (RED), proving bug-661 without relying on race timing.
    • Requirements: 3.1, 3.2
    • Depends: 1.1, 1.2

  • 2. Durable commit mechanism (acknowledgment ⇒ majority persistence)

  • 2.1 Introduce durable-LSN tracking via a group-commit flusher

    • Repurpose the background fsync thread from a timer into a demand-driven flusher: an append signals it; it performs one fdatasync over all pending appends, advances a durable-LSN watermark, and wakes the commit evaluation.
    • Guard against lost wakeups: the signal is level-triggered on the appended-vs-synced gap so an entry is never considered durable before its fdatasync (gating item).
    • Observable: a unit test shows one fdatasync advances the durable-LSN past several appended LSNs under load, and the durable-LSN never exceeds the synced tip.
    • Requirements: 1.1, 1.6
    • Boundary: DurableCommit

  • 2.2 Count self toward the commit majority only when durable

    • Change the commit-majority evaluation so the local member's self-contribution is capped at the durable-LSN watermark, not the appended tip; clamp the watermark on WAL truncation.
    • Observable: a unit test shows committed_lsn does not advance over an entry until that entry is durable locally, and the self-cap equals the durable-LSN.
    • Requirements: 1.2, 1.4
    • Boundary: DurableCommit

  • 2.3 Pin standby persist-before-acknowledge with a regression test

    • Add a regression test asserting the standby apply path fdatasyncs a replicated entry before sending its acknowledgment.
    • Observable: the test fails if the standby ACK is emitted before the durable write and passes against the current behavior.
    • Requirements: 1.3
    • Boundary: DurableCommit

  • 2.4 Reconcile the dormant synchronous-append commit path

    • The synchronous-append path advances the commit position directly on majority acknowledgment and is built on the premise that the append already fsync'd inline — a premise group-commit removes. Confirm it has no production caller and delete it, or route it through the same durable-majority evaluation so it can never advance the commit position on a non-durable entry.
    • Observable: a code search shows no path advances the commit position on majority ACK without the durable precondition; the dormant path is removed or re-routed, and a test guards against a future caller reintroducing an ACK-without-durability commit.
    • Requirements: 1.1, 1.2
    • Boundary: DurableCommit
    • Depends: 2.1

  • 3. Recovery integrity (no silent truncate; durable floor)

  • 3.1 Return a recovery integrity verdict and mark a truncated member non-promotable

    • Make WAL replay distinguish a clean log end from a corruption-stopped end (CRC chain break / mismatch / short read) and surface that verdict; a corruption-truncated recovery is never reported as a clean recovery and sets a member-level "recovery-truncated" flag that the promotion gate (4.3) consumes.
    • Observable: a unit test injecting a CRC break at the first entry yields a TRUNCATED verdict and sets the non-promotable flag, while an intact log yields CLEAN; an empty first-boot WAL is CLEAN (not corruption).
    • Requirements: 2.1
    • Boundary: RecoveryIntegrity

  • 3.2 Pin the fail-loud vs fence boot policy as a decision with a verification table

    • Pin the concrete policy (gating item, decision only — no behavior change yet): a truncated member fences from leadership at boot, attempts catch-up from a healthy peer, and terminates loudly only on a bounded failure to reach a committed-consistent state — never a silent indefinite fence. Encode the decision as a table of input states → expected outcome.
    • Observable: the policy and its decision table are recorded, and skeleton tests assert each row's expected outcome (initially failing), establishing the contract 3.3 and 4.3 implement.
    • Requirements: 2.2, 2.4
    • Boundary: RecoveryIntegrity

  • 3.3 Implement loud FATAL on bounded-unrecoverable recovery

    • Implement the FATAL branch of the 3.2 policy: when a recovery-truncated member cannot reach a committed-consistent state within the bounded catch-up window, terminate loudly with the truncation boundary logged; a reachable healthy peer never triggers FATAL.
    • Observable: the 3.2 decision-table rows for the FATAL/no-FATAL cases pass; logs show the truncation boundary on FATAL.
    • Requirements: 2.4
    • Depends: 3.1, 3.2
    • Boundary: RecoveryIntegrity

  • 3.4 Re-derive the durable floor from the recovered WAL tip

    • On recovery, publish the member's durable floor as the highest intact replayed LSN so later advertisement is backed by durable state rather than a volatile in-memory position.
    • Precision: this floor is the durable last-log index (WAL tip), used by the Raft freshness gate — not the commit position; the post-election safe-commit point continues to come from voter replies, not from this floor.
    • Observable: a unit test shows that after a truncating restart the published durable floor equals the highest intact LSN (the WAL tip), not a stale higher in-memory value or the commit position.
    • Requirements: 2.3
    • Boundary: RecoveryIntegrity

  • 4. Promotion fence and durable-backed freshness

  • 4.1 (P) Pin the freshness-floor formula and re-verify election safety and liveness

    • Define the exact reconciliation of the durable-derived freshness floor against the existing in-memory floor — the durable quantity is the durable last-log index (WAL tip), not the commit position — then re-check it against raft/raft.tla for Leader Completeness AND liveness (no election livelock) plus the Protocol Verification Checklist (gating item; analysis only, no shared source files).
    • Scope of the raft.tla check: it validates the election/freshness logic (the mlastLogIndex/LastTerm semantics this change touches), which raft.tla models directly. It does NOT validate the durability of that floor — raft.tla assumes a durable log (see 5.3). The durability of the WAL-tip derivation is verified by tests (3.4), not by raft.tla.
    • Observable: the pinned formula is recorded and the model/checklist verification passes for both a truncated-candidate-denied case and a longest-durable-log-still-elects case.
    • Requirements: 2.3
    • Boundary: FreshnessFloor

  • 4.2 Derive the vote and PreVote freshness floor from durable WAL state

    • Implement the pinned formula so a candidate cannot advertise, and a voter cannot grant against, a position beyond durable WAL state; the post-election safe-commit point continues to come from voter replies, never a stale ctrlhello.
    • Observable: a node restarted with a truncated log is denied (vote and PreVote), while the node holding the longest durable log still wins — no livelock.
    • Note: 4.2 and 4.3 both edit the same election code (cluster.c vote/PreVote and ha.c promotion); they are sequential (4.2 before 4.3), not parallel.
    • Requirements: 2.3
    • Depends: 4.1, 3.4

  • 4.3 Add the pre-promotion eligibility gate and fence release

    • Before a member becomes primary, refuse promotion if it carries the recovery-truncated flag (from 3.1) or its durable position is below the cluster committed high-water mark; extend the existing catch-up fence to cover the promoting/recovered member and release it when catch-up passes the last committed boundary. Reuse the durable-LSN truncate-clamp from 2.2 so the gate evaluates a clamped durable position at the promotion-path truncate site.
    • Observable: a recovery-truncated or behind member is denied promotion until catch-up completes, then regains eligibility; a hollow node cannot win even at minimal quorum.
    • Requirements: 2.2, 2.5, 2.6
    • Depends: 4.2, 3.1, 3.2, 2.2

  • 4.4 Bounded-window catch-up before FATAL (fence does not FATAL immediately)

    • The promotion gate (4.3) currently FATALs a recovery-truncated/behind member immediately at the promotion instant when no granting voter has a live endpoint AT THAT INSTANT — a transient no-peer snapshot during aggressive failover. Per the 3.2 decision table (rows 3/5) a member with a (momentarily) reachable peer must FENCE→catch-up→ELIGIBLE, NEVER immediate-FATAL; FATAL is reached ONLY after a BOUNDED failure to reach a committed-consistent state. Implement the deferred bounded-window catch-up: on FENCE (or would-be-FATAL no-peer), keep the member alive in in_catch_up, schedule a one-shot delaymgr timer for DEFAULT_RECOVERY_CATCHUP_WINDOW_MS, and reach the 3.3 FATAL ONLY from that timer if the member is STILL recovery-truncated AND durable_floor < cluster HWM AND no healthy peer / no catch-up progress when it fires. Re-derive eligibility (release the fence) when catch-up brings durable_floor ≥ HWM. Never FATAL synchronously in raft_cb_become_leader; never fence indefinitely.
    • Observable: a recovery-truncated node whose peers are transiently unreachable FENCES (stays alive) and is NOT FATAL'd; once a healthy peer is reachable and catch-up passes the committed boundary it regains eligibility; FATAL fires only after the bounded window with no peer/progress (unit-tested via the persist_fatal_hook + a short window). The rolling SIGKILL soak (task 5.2) keeps the cluster available (always re-elects) with zero acknowledged-job loss.
    • Requirements: 2.2, 2.4, 2.6
    • Depends: 4.3, 3.3
    • Boundary: PromotionFence

  • 5. Integration and validation

  • 5.1 Wire durable-majority commit end to end

    • Connect the durable-LSN self-count and the commit barrier so the client reply is released only after the entry is durable on a majority; assert liveness (the flusher does not stall heartbeat/election handling).
    • Observable: an integration test confirms reply-ok only after durable-majority, killing the sole durable contributor mid-commit leaves the acknowledged op present on the survivors, and the full controller suite passes under ASAN.
    • Requirements: 1.1, 1.4, 1.5, 1.6, 2.5
    • Depends: 2.2, 4.2

  • 5.2 Prove zero acknowledged-job loss across failover

    • Run the deterministic durability E2E and the rolling SIGKILL+restart soak; both must show every acknowledged job surviving every failover.
    • Observable: the deterministic mode that was RED in 1.3 now passes (GREEN), and the soak reports zero DATA LOSS across rounds.
    • Requirements: 1.1, 1.5, 2.2, 2.3, 2.6
    • Depends: 5.1, 4.3, 1.3

  • 5.3 Re-verify the formal safety checklist and flip the durability gap note

    • Re-run the raft/raft.tla alignment and the Protocol Verification Checklist (commit rule, leader completeness, commitIndex monotonic) against the integrated implementation.
    • IMPORTANT — raft.tla does NOT model durability: it restores log intact from "stable storage" on restart (raft.tla:165-174), i.e. it assumes what bug-661 violates. A passing TLC/alignment run on the unmodified spec therefore does NOT prove the commit-durability invariant. That invariant is verified by the unit/integration/E2E tests (2.x, 5.1, 5.2) plus the manual checklist — not by raft.tla. Do not conclude durability is proven from raft.tla alone. Formal durability proof would require extending raft.tla with a durable-vs-volatile log model (out of scope unless explicitly opted in).
    • Update src/controller/CLAUDE.md: convert the "Commit Durability — KNOWN GAP (bug-661)" note into the now-true guarantee and tick the post-ha-commit-durability checklist item.
    • Observable: the checklist passes with the durable self-count and the durable-backed freshness floor in place; the durability invariant is backed by passing tests (not by raft.tla); the CLAUDE.md gap note is removed; any deviation is recorded.
    • Requirements: 1.2, 2.3
    • Depends: 5.1

Implementation Notes

  • 1.1: Config plumbing routes through myconf_t.wal_sync_ms + persist_config_set_wal_sync_ms() (0-sentinel = keep DEFAULT_WAL_SYNC_MS), NOT a new config.h constant (design File Structure Plan keeps DEFAULT_WAL_SYNC_MS). The override is applied at BOTH persist_init sites — myapp_run step-6 (production path) and cluster_init_phase2 (guarded by wal_path[0]=='\0', skipped in production). They are mutually exclusive; apply any new persist_config override at both sites or it is silently dropped. Pre-existing latent bug (do NOT fix here): --sync-timeout-ms is applied only in phase2, so it is ignored on the production startup path — relevant if a later task relies on sync_timeout_ms.
  • 1.2: Test seam = persist_test_durable_lsn_on_disk(persist_t*) (decl persist.h, impl persist.c, all #ifdef XCE_TESTING) — re-opens WAL segment files from disk and CRC-validates the chain (read-only, state-free) to return the highest fully-persisted LSN; new test testsuite/test_commit_durability.c (registered in meson.build + controller_test.c). Production xce_controller links without it (proven via nm). DRY NOTE: ~115 lines of segment-scan/CRC-chain logic are duplicated from the static replay_wal; tasks 3.1 (recovery verdict) and 3.4 (durable floor from WAL tip) touch the SAME scan/CRC logic — consider extracting a shared read-only wal_scan_durable_lsn-style helper there and routing this seam through it (avoid a third copy). XCE_TESTING is defined only for controller_unit_test (src/controller/meson.build:167).
  • 1.3: Deterministic mode = bash src/tools/test-commit-durability.sh --deterministic proves the durability GAP via strace, NOT joblist data-loss. SCOPE CLARIFICATION (review-ratified): single-host SIGKILL committed-job loss is physically NON-deterministic — persist_wal_async pwrites inline (page cache survives process death) and standbys fdatasync-before-WalAck (persist.c:515), so a committed job is always durable off the primary; a data-loss run flips GREEN/RED/RED. The deterministic slice: with --wal-sync-ms 30000 the primary acks "jobsubmit ok" with ZERO primary fdatasync in the submit→ack window (exec-wrap strace -f -tt -e trace=fdatasync,fsync; PTRACE_ATTACH -p is yama-blocked). RED = in-window primary syncs==0 (15/15 across 5 runs; primary=0 vs standby=2). This is a valid RED→GREEN gate: the task-2.x fsync-before-ack fix makes the primary count ≥1 ⇒ GREEN. Original racy soak retained as the default mode. Boundary: only src/tools/test-commit-durability.sh (flag plumbed via deploy-ha.sh start.sh $* passthrough — no C edits). For task 5.2's E2E, prefer this strace gap-proof over joblist-loss for a deterministic durability assertion.
  • 2.1: persist_t.durable_lsn (_Atomic uint64_t, accessor persist_durable_lsn()) = prefix watermark advanced ONLY after a successful fdatasync. fsync_worker is now a demand-driven group-commit flusher: persist_wal_async pwrites under p->lock, releases, then signals fsync_cond. Lost-wakeup guard is LEVEL-triggered on flusher_work_pending_locked (durable_lsn < current_lsn-1), re-checked under p->lock before wait and after each flush (reviewer-confirmed sound). Invariants: monotonic, durable_lsn <= current_lsn-1, clamped on truncate (clamp_durable_lsn_locked at both truncate paths). fail-loud rc-gate: durable_lsn does NOT advance on fdatasync error (all 4 sites: flusher main/fallback, persist_stop, persist_flush) — logs ERROR. Test fault-injection seam: #ifdef XCE_TESTING toggle persist_test_set_force_fsync_fail() (production-excluded, nm-verified). NOT yet consumed by commit (that is 2.2). FOLLOW-UP (non-blocking, out of scope for 2.1): bound the flusher retry on SUSTAINED fdatasync failure (backoff / rate-limited logging) — currently tight-spins (releases p->lock each iter, so liveness OK, but CPU/log burn on a degrading disk). NOTE: a HANGING (not erroring) fdatasync blocks appends since it runs under p->lock — pre-existing, not 2.1's boundary.
  • 2.2: majority_candidate_locked (commit.c:93) self-cap = persist_durable_lsn(ce->p) (was highest_appended_lsn); appended tip kept only for the assert(cand <= highest_appended_lsn) never-beyond-log check. So committed_lsn cannot advance over an entry until it is durable locally (Req 1.2/1.4). Durable-advance WAKE (the wire 2.1 deferred): persist defines a callback hook on_durable_advance(void*)/durable_cb_ctx + persist_set_durable_cb(); commit registers commit_on_durable_advance (ctx=engine) in commit_engine_init, unregisters in commit_engine_fini. Flusher invokes it ONLY when durable_lsn advanced, AFTER releasing p->lock → callback takes ce->lock + broadcasts ce->cond. Respects commit→persist dependency direction (persist never includes commit). Lock order p->lock→ce->lock only (cycle-free). Lost-wakeup-free: broadcast follows the release-store; waiter re-reads durable under ce->lock; timedwait backstop. Shutdown UAF closed: persist_stop JOINS the flusher BEFORE commit_engine_fini (cluster.c:1675 vs 1695); final stop-flush does NOT fire the callback; fini also unregisters defensively. GOTCHA (bug-704): self-cap broke 4 existing commit-path fixtures (test_repl_majority/coldstart_lsn0/commit_barrier_rollout/demotion_convergence) that primed current_lsn but not durable_lsn — fix = prime durable_lsn = appended tip in any in-memory fixture that sets current_lsn without writing real WAL bytes (the flusher can't advance durable for a fake log). Any future commit-engine test must prime durable_lsn too.
  • 2.3: Standby persist-before-ACK pinned + Req-1.3 hole closed. persist_wal_write_replicated (persist.c:741) now rc-gates the inline fdatasync: on failure (or flusher_fsync_forced_fail) it logs ERROR + return -EIO (symmetric with the 2.1 flusher gate) — the standby will NOT ACK a non-durable entry. Caller ha_apply_single_entry (ha.c:1135-1166) ALREADY routes a negative return to no-apply/no-ACK (ha_send_wal_ack_reply reached only on rc==0), so NO ha.c change was needed (boundary stayed persistence-only). Ordering pin = #ifdef XCE_TESTING atomic_uint test_replicated_fdatasync_count incremented at the sync site; test_replicated_persist_syncs_before_return asserts it increments inside the call (page-cache means a disk re-read can't prove fsync — use the counter). test_replicated_sync_failure_no_ack REDs without the gate. Seam production-excluded (nm-verified). HOUSEKEEPING: controller tests mkdtemp into /tmp/xce_* and don't clean up — thousands accumulate and eventually make mkdtemp fail → misleading suite-wide "Expected Non-NULL" cascade. Run rm -rf /tmp/xce_* if that appears (pre-existing test pattern, not a regression).
  • 2.4: SPEC INACCURACY corrected — persist_wal_sync_append is NOT dormant; it is the LIVE job-submit path (persist_job_hook_fun calls it at persist.c:1911). Took the "route through durable-majority eval" option (delete infeasible). Production path (ce!=NULL, lsn!=0) was already durable-safe via 2.2's majority_candidate_locked self-cap. Closed the hazard in the LEGACY branch: the former unconditional atomic_store(committed_lsn, written_lsn) on majority ACK is now sync_append_legacy_commit_store() which advances ONLY when written_lsn <= persist_durable_lsn(p) (LSN-0 edge: store of 0 valid). Added the design's debug invariant committed_lsn <= durable_lsn (#ifdef XCE_TESTING assert at commit.c:162 + inside the legacy store) as the future-proof guard. Fixed the stale "after local fsync via persist_wal_async" comment (2.1 deferred the fsync). CODE-SEARCH (authoritative): the ONLY committed_lsn stores are — engine advance (commit.c, durable-capped by 2.2), legacy sync_append (now gated), and the two persist_truncate_wal_above cutoff stores (NOT ACK-driven; each immediately clamp_durable_lsn_locked). ha.c/ha_convergence.c stores are last_known_committed_lsn (DIFFERENT field). So no path advances commit on ACK without the durable precondition. Seam persist_test_sync_append_legacy_commit_store is production-excluded.
  • 3.1: recover_verdict_t {RECOVER_CLEAN, RECOVER_TRUNCATED} (persist.h) + persist_t.recovery_verdict field + accessors persist_recovery_verdict()/persist_recovery_truncated() (NOT XCE_TESTING-gated — 4.3 consumes them in production). replay_wal classifies: CRC chain break / CRC mismatch / short header/payload read → TRUNCATED; clean entry boundary / pre-allocated-zero tail / empty WAL / snapshot-sentinel+clean-replay → CLEAN. Verdict is monotonic (init CLEAN once; only ever set TRUNCATED; a later clean segment can't un-set it). Verdict = STRUCTURAL integrity, NOT "behind the cluster" (the behind-high-water case is 4.2/4.3). 3.1 ONLY sets state + WARNs — does NOT FATAL (3.3) or fence (4.3). DRY: did NOT extract a shared scanner (replay_wal mutates persist_t; the 1.2 seam is read-only) — no third copy added. ENV FINDING (see cerebrum 2026-06-18): this sandbox's /tmp can be an overlay that EIOs on fdatasync; because committed_lsn is now durable-gated (2.x), an fdatasync EIO correctly HOLDS committed_lsn, which makes test_fact_hook_append_is_retained_and_nonblocking (commit_barrier_rollout) FAIL on overlay /tmp — confirmed pre-existing (fails identically on the clean pre-spec baseline), NOT a regression. Final validation (5.x) must run on a real fsync-able fs.
  • 3.2: DECISION-ONLY (no production change). Boot Policy Decision Table recorded in design.md §"Boot Policy Decision Table (task 3.2)" — 7 rows over {verdict CLEAN/TRUNCATED × at-above/below HWM × peer reachable × bounded-catch-up succeeds/fails} + snapshot-sentinel + empty-first-boot. Outcomes: ELIGIBLE / FENCE+CATCH-UP→ELIGIBLE / bounded FATAL. AUTHORITATIVE INVARIANT: never a silent indefinite fence — every truncated/behind member resolves to exactly one terminal (catch-up→ELIGIBLE, or BOUNDED FATAL). Snapshot-sentinel is NEVER FATAL on a legitimate sentinel. 7 skeleton tests in test_commit_durability.c (row1,2,3,4,4b,5,6) are TEST_IGNORE_MESSAGE-skipped (PENDING 3.3/4.3) so the suite stays GREEN — they are the RED contract 3.3 (FATAL rows) and 4.3 (fence/eligible rows) turn green. NOTE: pre-existing ASAN leaks in unrelated tests (test_demotion_convergence, ha_start_election_async, ha_rdhup_integration) make the STANDALONE controller_unit_test exit=1, but meson reports Fail:0 — don't be fooled by standalone exit code.
  • 3.3: FATAL branch = pure decision persist_recover_decision(recover_policy_inputs_t) → recover_decision_t {ELIGIBLE, FENCE, FATAL} (persist.c) + action persist_recover_fatal_if_unrecoverable() which logs the truncation boundary (durable_floor_lsn/cluster_hwm_lsn + window ms) at ERROR then terminates via persist_fatal_hook (extern void(*)(const char*), NULL in prod → tlog_exit(); abort(); mirrors ha_fatal_hook; tests install it to capture instead of abort). FATAL ONLY for bounded-unrecoverable + NO healthy peer (rows 4/4b); a reachable peer NEVER FATALs (gated behind if (!healthy_peer_reachable)); eligibility rows 1/2/6 never FATAL. Bound = FINITE DEFAULT_RECOVERY_CATCHUP_WINDOW_MS=30000 (persist.h) — keys off the catch_up_succeeded bounded-window result, never an indefinite wait. Turned 3.2 skeleton rows 4/4b GREEN + added test_boot_policy_peer_reachable_never_fatal; rows 1/2/3/5/6 stay IGNORE (FENCE→ELIGIBLE is 4.3). DEFERRED to 4.3/5.x: wiring this decision into the live boot/promotion path (3.3 is the unit-tested decision + terminate only; no ha.c/cluster.c edits).
  • 3.4: On recovery, persist_recover publishes the durable floor = highest intact replayed LSN (recovered WAL tip = current_lsn-1 after replay_wal) into durable_lsn via atomic_store (ASSIGN, NOT max — so a truncating restart lands at the LOWER intact tip, never over-advertising; this is the crux of Req 2.3). Added persist_durable_floor() (NULL-safe thin accessor) as the seam task 4.2 consumes. Floor is the durable LAST-LOG INDEX (WAL tip), NOT the commit position (committed_lsn) and NOT a volatile in-memory value. Invariant-safe (recovery/init-time; recovered entries are CRC-validated on-disk = genuinely durable; preserves durable_lsn <= current_lsn-1). 4.2 (ha.c/cluster.c) CONSUMES this floor in ha_vote_self_freshness — 3.4 only PUBLISHES (persistence-only). Phase 3 (recovery integrity) COMPLETE.
  • 4.1: ANALYSIS-ONLY (no .c/.h). Pinned freshness-floor formula in design.md §"Freshness-Floor Formula (task 4.1)" — THE CONTRACT 4.2 implements. CANDIDATE advertises BARE cand_lsn = persist_durable_floor(p) (durable WAL tip) — sites ha.c:3660-3666 (real-vote) + ha.c:3735-3741 (PreVote) must call persist_durable_floor DIRECTLY, BYPASSING ha_vote_self_freshness on the LSN axis (that fn unconditionally folds in last_known_committed_lsn → max(durable_floor, learned) = the truncated-candidate-wins bug). VOTER floor = max(durable_floor, last_known_committed_lsn) — sites cluster.c:388-395/471-475 + ha.c:2243 keep ha_vote_self_freshness with local_lsn=durable_floor (the learned_committed backstop stays on the VOTER axis only). Grant iff cand_tag > floor_tag OR (==tag AND cand_lsn >= floor_lsn) (term-then-index, matches raft.tla LastTerm/mlastLogIndex |-> Len(log)). cand_tag/floor_tag = max(local_tag, learned_tag). SAFETY (Leader Completeness): quorum intersection Q_L∩Q_v ⇒ truncated candidate (durable tip < committed L) denied. LIVENESS (no bug-339 livelock): rests on D* (max durable tip in reachable majority); durable_floor(v) ≤ D* and learned_committed(v) ≤ L ≤ D*, so the most-durable candidate is always grantable. safe_committed_lsn STAYS voter-reply-sourced (unchanged). CAVEAT: raft.tla validates election/freshness LOGIC only, NOT durability (no TLC run — no toolchain; conceptual alignment) — durability verified by 2.x/3.4 tests. (1 remediation: candidate-vs-voter contradiction + §5b example fixed.)
  • 4.2: Implements the 4.1 formula. New ha_candidate_advertise_lsn(persist*) = bare persist_durable_floor. CANDIDATE sites advertise bare durable_floor for the LSN (tag still via ha_vote_self_freshness(...,&tag,NULL)): ha.c:~3690 (real election), ha.c:~3771 (PreVote), AND myapp.c:~234 (boot election — a THIRD candidate site the brief didn't name; fixed too, else a boot-time truncated candidate over-advertises). VOTER floor: cluster.c:~383 (real) + cluster.c:~471 (PreVote) feed local_lsn = persist_durable_floor(&c->persist) into ha_vote_self_freshness → floor = max(durable_floor, learned_committed). Comparison unchanged (term-then-index). ha.c:2243 legacy handle_request_vote is XCE_TESTING-only/param-driven — left unchanged. safe_committed_lsn UNTOUCHED (voter-reply-sourced). 3 tests in test_ha_vote_gate.c prove: candidate advertises bare durable_floor (not stale learned); voter durable-floor denies truncated; longest-durable grantable / no livelock. bug-339 regression test fixture primed durable_lsn=10 (model-preserving). INFO: truncated-deny proven at the freshness-comparison-expression level shared by both vote+PreVote paths (no dedicated live PreVote-handler truncation driver — adequate; nice-to-have for 5.x). GOTCHA for future election tests: the freshness floor now reads persist_durable_floor, so any vote/election fixture that sets applied_lsn/last_known_committed_lsn but not durable state will see floor/advertise=0 — prime durable_lsn to the modeled tip.
  • 4.3: Pre-promotion eligibility gate in raft_cb_become_leader (ha.c, post-truncate / pre-CTRL_PRIMARY, returns on refuse). ha_promotion_gate_decision (pure, delegates to 3.3's persist_recover_decision — table is single source of truth) + ha_evaluate_promotion_fence (live: ELIGIBLE clears in_catch_up, FENCE sets it, FATAL → 3.3 persist_recover_fatal_if_unrecoverable). REFUSE if persist_recovery_truncated OR persist_durable_floor < promotion_safe_lsn (the existing voter-reply-derived safe_committed_lsn, read AFTER persist_truncate_wal_above so it reflects 2.2's clamp). peer_reachable = some granting voter has a live endpoint (ectx->votes[i].vote_granted && .ep != NULL) — so a multi-node election winner ALWAYS has a peer ⇒ FENCE (never premature FATAL, honoring rows 3/5); FATAL only fires no-peer (single-node corrupt = genuinely unrecoverable, row 4). Reuses in_catch_up (NOT a parallel fence); release on a later promotion attempt once caught up (durable_floor ≥ HWM, not truncated) → ELIGIBLE clears the fence (Req 2.6, re-evaluation model). safe_committed_lsn arithmetic UNTOUCHED. Turned 3.2 rows 1/2/3/5/6 GREEN (0 ignored boot-policy rows remain) + minimal-quorum test (Req 2.5). DEFERRED to 5.1: the live bounded-window catch-up TIMER (grant DEFAULT_RECOVERY_CATCHUP_WINDOW_MS to find a peer before FATAL) — here catch_up_succeeded=false at the gate, so it FENCEs (peer) or FATALs (no peer) immediately; fail-loud-conservative, never silently leads hollow. NOTE: reviewed in MAIN CONTEXT (review subagent hit a spend limit) — suite green ×1 (Fail:0, all 9 boot-policy/gate tests PASS, test_fact_hook_append passed too since this shell's /tmp is fsync-able). Phase 4 COMPLETE.
  • 5.1: INTEGRATION verification — the end-to-end durable-majority path was ALREADY wired by 2.1/2.2/2.4/4.x (no production gap found); 5.1 adds 3 integration tests + a tiny #ifdef XCE_TESTING liveness-observability seam (persist_test_last_fdatasync_thread, nm-excluded from prod). test_durable_majority_commit_end_to_end: holds durability off (forced fsync-fail), delivers BOTH standby ACKs, asserts committed_lsn/WAIT do NOT release (ACK-majority alone insufficient) — then flush makes self durable ⇒ committed advances + WAIT releases rc=0; asserts committed_lsn <= durable_lsn. RED proof: injecting the pre-2.2 highest_appended_lsn cap trips assert(cand <= persist_durable_lsn). test_sole_durable_contributor_loss_survives (Req 1.5/2.5): property-asserted (committed ⇒ ≥⌊N/2⌋+1 durable copies, two persist dirs, drop one) — LIVE failover proof is 5.2. test_durability_work_off_iomgr_preserves_liveness (Req 1.6): seam records the flusher thread id; asserts fdatasync runs off the caller/iomgr thread + heartbeat reads stay <50ms during flushes. GOTCHA: a real persist with registered standbys needs the XCE_TESTING repl_broadcast_send_hook (drop) installed before append, else dummy endpoints trip an ASAN overflow in dataq_enq. CAVEATS (for 5.3/validation): (1) meson Fail:0 masks Unity sub-group failures — gate on grep -c :FAIL: testlog.txt==0; (2) run on a fsync-able fs (the pre-existing test_fact_hook_append EIO failure is /tmp-overlay-only). 4.3 catch-up-timer-before-FATAL still a follow-up. Reviewed in MAIN CONTEXT (subagent spend limit).
  • 4.4: Closed the 5.2-soak liveness gap. raft_cb_become_leader NO LONGER FATALs synchronously — on FENCE / would-be-FATAL (truncated or durable_floor < HWM) it calls ha_arm_promotion_fence_timer (sets in_catch_up, schedules a one-shot delay_task_ms(&c->delaymgr, ha_promotion_fence_window_ms(), 1, promotion_fence_timeout_fn, ctx)) and RETURNS without becoming primary. The timer callback (promotion_fence_timeout_fn, ha.c:702) re-reads LIVE state after the window: caught-up (!truncated && durable_floor>=HWM) → release fence, NO FATAL (Req 2.6); peer reachable (repl_active_standby_count>0) OR durable_floor advanced past the arm-time baseline → progress possible, leave fenced (existing catch-up machinery / next promotion-gate ELIGIBLE releases it), NO FATAL; ONLY still-truncated/behind + no-peer + no-progress → 3.3 persist_recover_fatal_if_unrecoverable (Req 2.4). UAF-safe cancel (ha_cancel_promotion_fence_timer: cancelled flag + atomic-exchange the stored ctx; handle cleared before the cancelled-check, mirrors raft_election_timeout_fn); cancelled in ha_fini; fail-loud if delay_task_ms itself fails (never fence indefinitely). Test window seam ha_set_promotion_fence_window_ms + driver ha_arm_promotion_fence_timer_for_test. 3 tests (defers-fatal-to-timer, released-on-catchup-no-fatal, cancel-prevents-fatal) with RED proof (re-injecting sync FATAL → 3 fails). Reviewed MAIN CONTEXT (subagent spend limit): suite :FAIL:==0, /tmp fsync-able this run. NOTE: this is the bounded-window timer 4.3/5.1 deferred; with it, 5.2's soak should keep the cluster available (truncated rejoiners catch up, not die).
  • REWORK (2026-06-18, user invariant — a controller MUST NEVER self-terminate): tasks 3.3/4.3/4.4 had implemented Req 2.4 "fail loud" as a SELF-ABORT (persist_recover_fatal_if_unrecoverable → tlog_exit(); abort() + persist_fatal_hook). That violated the invariant (a self-exited controller needs MANUAL admin recovery + leaves quorum degraded; a live retrying node self-heals when a peer returns) and was the true root cause of the 5.2 soak quorum collapse. CORRECTED: removed the abort/exit terminal entirely. New: persist_recover_loud_fence_if_unrecoverable(persist_t*) (NO abort) logs a loud operator-visible ERROR (truncation boundary vs cluster HWM) + sets sticky _Atomic bool recovery_unrecoverable (accessors persist_recovery_unrecoverable/persist_clear_recovery_unrecoverable); the member STAYS ALIVE, permanently non-promotable/fenced (in_catch_up + the sticky flag both consulted by the promotion gate), and KEEPS RETRYING catch-up. Decision enum RECOVER_DECISION_FATAL → RECOVER_DECISION_FENCE_UNRECOVERABLE (non-terminating). 4.4 timer no longer aborts — it re-emits the loud operator alert + re-arms (operator visibility), never exits. Flag + fence CLEAR automatically on catch-up (not truncated AND durable_floor ≥ HWM) → re-eligible (Req 2.6), fully automatic. persist_fatal_hook removed. Verified: grep/nm show NO abort/exit/tlog_exit on the recovery path; ASAN suite :FAIL:==0; reworked tests (row4/4b → loud_fence, unrecoverable-stays-alive-loud, released-on-catchup, cancel-stops-realert) PASS. Spec updated: requirements.md Req 2.4 + design.md (decision table rows 4/4b, RecoveryIntegrity, traceability, FATAL-vs-fence open question) reworded "FATAL/terminate" → "LOUD PERMANENT FENCE (non-promotable, stays alive, keeps retrying — NEVER self-exit)". PROJECT-WIDE GUIDANCE added: src/controller/CLAUDE.md §"Process Lifecycle (DESIGN INVARIANT)" + .kiro/steering/ha-async-io.md — controllers never self-terminate. (ha_self_restart execv-restart in convergence/demotion is a SEPARATE primitive, untouched.)
  • 5.2: PASS on the reworked (no-self-exit) build. (a) DETERMINISTIC E2E flipped RED→GREEN, stable 3/3 runs / 9-9 probes — in-window primary fdatasync ≥1 (=2) precedes the ack ("durable-before-ack"), the inverse of 1.3's unfixed RED. (b) ROLLING SIGKILL soak (6 rounds) exit 0 = ZERO acknowledged-job loss, cluster stayed continuously available, 0 self-terminations (the no-self-exit rework removed the abort that collapsed quorum in the first attempt). Validation-only (no production code). NOTE: ran in-sandbox via background+poll on a worktree deploy dir (avoids /tmp overlay EIO); the earlier collapse was the abort terminal, now corrected — a host re-run is still good practice but the in-sandbox soak now passes with the fix.
  • 5.3: Formal re-verification (conceptual — no TLA+ toolchain in env; project practice = manual alignment + the CLAUDE.md Protocol Verification Checklist). Checklist walked against the integrated impl, all hold: votedFor/currentTerm (untouched); commitIndex/committed_lsn monotonic + never exceeds durable_lsn (2.2/2.4 debug-assert); leader commits via per-entry majority ack (unchanged); safe_committed_lsn from voter replies (untouched, 4.2/4.3); WAL truncation only above the safe point + durable_lsn clamped on truncate; freshness gate term-then-index with durable-backed LSN (4.1 pinned vs raft.tla mlastLogIndex/LastTerm; candidate bare durable_floor, voter floor max(durable_floor, learned)); contiguous-prefix commit; durable_lsn prefix watermark; causal-order append; and the NEW item — a member counts toward the commit majority only at its durable LSN, acknowledged⇒durable-on-majority — now TRUE. raft.tla alignment: the election/freshness logic maps faithfully; raft.tla does NOT model durability (assumes a durable log, restores log intact on restart raft.tla:165-174) so it CANNOT prove the commit-durability invariant — that invariant is backed by tests 2.x/5.1 + the deterministic RED→GREEN E2E + the zero-loss/available soak (5.2), NOT by raft.tla. src/controller/CLAUDE.md: "Commit Durability — KNOWN GAP (bug-661)" flipped to "GUARANTEED / CLOSED (landed 2026-06-18)" with the mechanism list (incl. the no-self-exit loud fence); the post-ha-commit-durability checklist item ticked [x]. ALL 17 tasks (1.1–5.3) + the no-self-exit rework COMPLETE.