natsnet/docs/plans/2026-02-27-batch-31-raft-part-2-design.md

Batch 31 Raft Part 2 Design

Date: 2026-02-27
Batch: 31 (Raft Part 2)
Scope: 53 features + 19 unit tests
Dependencies: batch 30 (Raft Part 1)
Go source: golang/nats-server/server/raft.go

Problem

Batch 31 covers the second Raft tranche in raft.go (roughly lines 3239-5038), focused on catchup/snapshot transfer, append-entry processing, WAL consistency, quorum tracking, vote request/response handling, and leadership state transitions. The mapped test set (19 tests) is concentrated on candidate/leader transitions, quorum correctness, membership-change edge cases, and snapshot/catchup behavior.

The design goal is to produce an execution-ready plan that enforces evidence-based status changes and prevents placeholder drift across both production features and tests.

Context Findings

Required command results

• batch show 31 --db porting.db
  • Status: pending
  • Features: 53 (currently deferred)
  • Tests: 19 (currently deferred)
  • Depends on: 30
  • Go file: server/raft.go
• batch list --db porting.db
  • Batch 31 is directly gated by Batch 30 and itself gates Batch 32 (JS Cluster Meta).
• report summary --db porting.db
  • Overall progress: 1924/6942 (27.7%)
  • Deferred backlog remains large; verification discipline is required.

Feature and source mapping findings

• Batch 31 feature IDs map in order to raft.go methods from:
  • sendSnapshotToFollower through updateLeader (2733-2750)
  • processAppendEntry through setWriteErrLocked (2751-2777)
  • isClosed through switchToLeader (2778-2796)
• Existing .NET Raft surface is in:
  • dotnet/src/ZB.MOM.NatsNet.Server/JetStream/RaftTypes.cs
• Current comments in RaftTypes.cs still describe algorithm methods as stubbed; Batch 31 must replace those gaps with concrete behavior and tests.

Test mapping findings

• All 19 mapped tests are from server/raft_test.go and map to RaftNodeTests methods.
• dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RaftNodeTests.Impltests.cs does not currently exist, so Batch 31 planning should include creating it.
• The mapped tests are behavior-heavy; they cannot be verified using placeholder assertions.

Approaches

Approach A: Monolithic implementation of all 53 features and 19 tests in one pass

• Pros: single sweep.
• Cons: high regression risk, weak traceability, hard to isolate failures.

Approach B (Recommended): Three feature groups (<=20 each) plus two test waves

• Features are implemented in ordered method clusters, each with strict gates before status updates.
• Tests are ported in two behavioral waves (state/quorum first, then snapshot/membership edge cases).
• Pros: bounded scope, better failure isolation, cleaner status evidence.
• Cons: more checkpoint overhead.

Approach C: Test-first across all 19 tests, then fill feature gaps

• Pros: quickly exposes missing behavior.
• Cons: expensive thrash because many tests depend on broad feature slices.

Decision: Approach B.

Proposed Design

1. Architecture and file strategy

• Keep Raft runtime behavior in JetStream/RaftTypes.cs, with optional split into partials if file size hurts reviewability:
  • RaftTypes.Catchup.cs
  • RaftTypes.AppendProcessing.cs
  • RaftTypes.Elections.cs
• Keep test implementation in dedicated mapped backlog file:
  • dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RaftNodeTests.Impltests.cs
• Reuse existing support types (IpQueue<T>, Channel<T>, lock + Interlocked) and avoid introducing new infra unless required for deterministic testability.

2. Feature slicing (max ~20 per group)

• Feature Group A (18): catchup/snapshot/commit foundations
  2733,2734,2735,2736,2737,2738,2739,2740,2741,2742,2743,2744,2745,2746,2747,2748,2749,2750
• Feature Group B (18): append-entry processing and peer/WAL state
  2751,2752,2753,2754,2755,2756,2758,2759,2760,2761,2765,2766,2767,2768,2769,2772,2776,2777
• Feature Group C (17): vote/RPC/state transitions
  2778,2779,2780,2783,2784,2785,2786,2787,2788,2789,2790,2791,2792,2793,2794,2795,2796

3. Test slicing

• Test Wave T1 (10): state/quorum/election behavior
  2626,2629,2635,2636,2663,2664,2667,2687,2690,2692
• Test Wave T2 (9): snapshot/catchup/membership-vote edge cases
  2650,2651,2693,2694,2702,2704,2705,2712,2714

4. Verification model

• Enforce per-feature and per-test loops (red/green + stub scan + build/test gates).
• Enforce status-update chunking (<=15 IDs per feature/test batch-update).
• Enforce checkpoint protocol after every group/wave before proceeding.

5. Stuck-item policy

• A blocked item is not left as pseudo-implemented.
• If blocked, set deferred immediately with explicit reason via --override, then continue with next unblocked ID.

Risks and Mitigations

• Risk: Batch 30 dependency incomplete blocks execution.
  Mitigation: preflight dependency gate is mandatory; no Batch 31 status updates until Batch 30 is complete/ready.
• Risk: Large method processAppendEntry causes hidden regressions.
  Mitigation: isolate with focused tests per behavior branch plus class-level gates.
• Risk: fake progress via placeholder methods/tests.
  Mitigation: mandatory anti-stub scans and hard promotion gates.

Success Criteria

• All 53 features are either verified with evidence or deferred with explicit blocker reason.
• All 19 tests are either verified with execution evidence or deferred with explicit blocker reason.
• No placeholder/stub patterns in touched production or test code.
• Batch-completion readiness is auditable through build/test outputs and chunked status updates.

Non-Goals

• Executing implementation in this design doc.
• Implementing Batch 32+ scope.
• Building new distributed integration infrastructure beyond deterministic unit-level needs.