natsnet/docs/plans/2026-02-27-batch-30-raft-part-1-design.md

# Batch 30 Raft Part 1 Design

**Date:** 2026-02-27  
**Batch:** 30 (`Raft Part 1`)  
**Scope:** 85 features + 414 unit tests  
**Dependencies:** batches `4` (Logging), `18` (Server Core)  
**Go source:** `golang/nats-server/server/raft.go`

## Problem

Batch 30 is the first major Raft execution tranche and includes foundational node bootstrap, election/follower/leader loops (through `runCatchup`), append-entry/vote encoding helpers, and server-level Raft-node registration and lookup methods. The mapped test surface is very large (414 tests) and includes both direct Raft tests and broad JetStream cluster regressions.

The design goal is to make Batch 30 executable in a deterministic, evidence-driven way without repeating the placeholder-test/stub drift seen in earlier backlog files.

## Context Findings

### Required command results

- `batch show 30 --db porting.db`
  - Status: `pending`
  - Features: `85` (all currently `deferred`)
  - Tests: `414` (all currently `deferred`)
  - Depends on: `4,18`
- `batch list --db porting.db`
  - Batch 30 is ordered before Batch 31 (`Raft Part 2`) and is a dependency anchor for JetStream cluster batches.
- `report summary --db porting.db`
  - Overall progress: `1924/6942 (27.7%)`
  - Deferred backlog remains dominant, so verification rigor is mandatory.

### Feature-map and codebase findings

- Batch 30 feature IDs are concentrated in `raft.go` line ranges `137-3237` plus package/helper functions in `4354-4753`.
- Existing .NET Raft baseline exists in `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/RaftTypes.cs`, but many mapped Batch 30 method targets are still missing or only partially approximated.
- Server-level mapped methods (`BootstrapRaftNode`, `InitRaftNode`, `StartRaftNode`, `RegisterRaftNode`, etc.) do not currently exist as first-class `NatsServer` methods.

### Test-map findings (critical)

- Batch 30 tests are highly skewed:
  - `366` tests map to feature `2683` (`raft.shutdown`)
  - `3` tests map to feature `2715` (`appendEntry.encode`)
  - remaining tests map to external feature IDs (45 tests)
- Only `19` tests come from `server/raft_test.go`; the rest are mostly JetStream cluster/supercluster/concurrency/MQTT regression tests that rely on raft behavior transitively.
- Existing `ImplBacklog/*.Impltests.cs` files contain many superficial placeholder-style tests and cannot be treated as verification evidence.

## Approaches

### Approach A: Full-surface implementation (85 features + all 414 tests in one pass)

- Pros: maximal immediate tracker movement.
- Cons: extremely high risk, weak causality, and likely stub/fake-pass relapse.

### Approach B (Recommended): Feature-first Raft core in five groups, then two-tier test strategy

- Tier 1: implement and verify all 85 Batch 30 features in grouped, dependency-ordered slices.
- Tier 2: port direct Raft unit tests first, then process broader mapped regression tests class-by-class with explicit defer rules when runtime infra is missing.
- Pros: coherent sequencing, auditable status transitions, supports strict anti-stub controls.
- Cons: more checkpoints and status operations.

### Approach C: Infra-first (build cluster harness before feature completion)

- Pros: can unlock larger integration tests earlier.
- Cons: violates YAGNI for this batch and delays core feature parity.

**Decision:** Approach B.

## Proposed Design

### 1. Architecture and file strategy

- Keep Raft model/codec/state-machine logic centered in `JetStream/RaftTypes.cs`, but split into partial files when method count becomes unreviewable (for example: lifecycle, codecs, follower/leader loops).
- Add explicit `NatsServer` Raft integration surface in a dedicated partial (`NatsServer.Raft.cs`) instead of reflection-only lifecycle hooks.
- Preserve existing locking/concurrency primitives already used in repo (`ReaderWriterLockSlim`, `Interlocked`, `Channel<T>`, `IpQueue<T>`), mapping Go intent rather than line-by-line syntax.

### 2. Feature grouping (max ~20 per group)

- **Group A (15):** bootstrap/init/server registry and early apply/snapshot prep  
  `2599,2600,2601,2602,2603,2607,2608,2609,2610,2611,2612,2613,2614,2615,2629`
- **Group B (14):** snapshot lifecycle + leader-state helpers/campaign hooks  
  `2634,2637,2639,2645,2646,2647,2651,2652,2653,2659,2663,2664,2665,2674`
- **Group C (20):** node runtime loop and follower pipeline scaffolding  
  `2683,2684,2685,2686,2687,2688,2689,2690,2691,2692,2693,2694,2695,2696,2697,2698,2701,2702,2703,2704`
- **Group D (19):** entry construction/encoding + membership-change handlers  
  `2705,2706,2707,2708,2709,2710,2711,2712,2714,2715,2716,2717,2718,2719,2720,2721,2722,2723,2724`
- **Group E (17):** leader loop/catchup + peer-state and vote persistence helpers  
  `2725,2727,2728,2729,2731,2732,2757,2762,2763,2764,2770,2771,2773,2774,2775,2781,2782`

### 3. Test design

- **Tier T1 (Raft-direct tests, highest value first):** `server/raft_test.go` mapped IDs (`2618,2619,2621,2623,2625,2632,2633,2639,2642,2675,2700,2701,2706,2707,2708,2709,2710,2711,2713`).
- **Tier T2 (transitive regression tests):** remaining mapped classes (`JetStreamClusterTests*`, `JetStreamSuperClusterTests`, `ConcurrencyTests*`, `MqttHandlerTests`, etc.) processed only with real behavioral assertions; otherwise explicitly deferred with reason.
- Existing placeholder tests are not accepted as evidence; they must be replaced or remain deferred.

### 4. Verification model

- Enforce per-feature and per-test loops with mandatory build/test gates before any status promotions.
- Enforce max `15` IDs per `feature/test batch-update` command.
- Require checkpoint protocol between tasks (stub scan, build, targeted tests, full unit test, then status updates).

### 5. Error handling and stuck policy

- If a feature/test is blocked by missing infrastructure, missing prerequisite behavior, or non-deterministic harness gaps:
  - do not leave placeholders,
  - do not force fake-pass tests,
  - mark `deferred` with explicit blocker reason,
  - continue with next unblocked ID in current group.

## Risks and Mitigations

- **Risk:** `raft.shutdown` mapping concentration (366 tests) causes noisy/non-actionable test wave.  
  **Mitigation:** process tests by class and behavioral relevance; require per-test evidence and deferred reasons for infra-blocked cases.
- **Risk:** large `RaftTypes.cs` file becomes unreviewable.  
  **Mitigation:** allow controlled partial-file split while preserving namespaces and API shape.
- **Risk:** false progress via stubbed placeholders in `ImplBacklog`.  
  **Mitigation:** mandatory anti-stub scans and hard promotion gates.

## Success Criteria

- All 85 features are either `verified` with evidence or `deferred` with specific blocker reason (no placeholders).
- Batch 30 mapped tests are processed under the same rule: verified only with real execution evidence, otherwise deferred with explicit reason.
- No new stub/fake-pass patterns in touched production or test files.
- The implementation plan includes strict verification and anti-stub guardrails adapted to both features and tests.

## Non-Goals

- Executing implementation in this design document.
- Completing downstream Batch 31+ raft/clustering behavior that is outside Batch 30 feature IDs.
- Building new distributed integration infrastructure beyond what is needed for deterministic unit-level verification.