natsdotnet/docs/plans/2026-02-25-gap-port-raft-design.md

RAFT Full Parity Design

Date: 2026-02-25
Category: raft
Gap Inventory: gaps/raft.md
Target Outcome: Full Go-to-.NET behavioral parity for this category.

Assumptions

• Full parity is the required outcome.
• No additional requirements gathering is needed for this pass.
• Existing public .NET APIs are preserved unless parity requires targeted, documented adjustments.

Current State Snapshot

• MISSING: 99
• PARTIAL: 38
• PORTED: 46
• NOT_APPLICABLE: 13
• DEFERRED: 0
• Open parity work items: 137

Approaches Considered

1. Symbol-first closure (Recommended): execute directly against each MISSING and PARTIAL row in gaps/raft.md, closing items in deterministic order. Trade-off: strongest traceability and auditability, but can require broad context switching.
2. Test-first closure: derive all work from Go test scenarios first, then backfill missing symbols. Trade-off: maximizes behavioral confidence, but can miss non-test-covered API and helper parity.
3. Vertical runtime slices: port connect/auth/pubsub/cluster flows end-to-end before moving to next slice. Trade-off: smoother integration validation, but weaker one-to-one mapping against inventory rows.

Recommended Design

Architecture

Use the gap inventory as the authoritative backlog. For each row, implement or complete the .NET equivalent, then attach test evidence and update the inventory status. Keep implementation inside existing category boundaries and only refactor when needed to match Go behavior.

Components

• Backlog driver: gaps/raft.md (row-level tracking for all parity items).
• Implementation surface: category-specific .NET source files.
• Verification surface: category-specific .NET tests plus cross-module regression tests.
• Parity bookkeeping: updates to gaps/raft.md and gaps/stillmissing.md after each closure batch.

Data Flow

1. Read one MISSING or PARTIAL row from gaps/raft.md.
2. Inspect referenced Go implementation and tests.
3. Add/adjust .NET implementation in listed category files.
4. Add failing .NET tests that reproduce the missing/partial behavior, then make them pass.
5. Re-run targeted and regression tests.
6. Update the row to PORTED (or keep PARTIAL with explicit residual notes).

Error Handling and Risk Controls

• Avoid broad rewrites; prefer narrow patches tied to specific inventory rows.
• Preserve protocol and timing semantics when replacing Go concurrency constructs with .NET async patterns.
• Treat edge cases in Go tests as mandatory parity requirements unless explicitly marked NOT_APPLICABLE.
• Require evidence (tests + inventory status updates) before declaring row completion.

Testing Strategy

• Add or expand tests for each row moved from MISSING/PARTIAL toward PORTED.
• Prioritize wire/protocol compatibility, lifecycle transitions, auth boundaries, and backpressure/timeout behavior.
• Keep category-targeted tests fast; run full NATS.Server.Tests regression before closure.

Definition of Done

• All category rows are either PORTED or explicitly justified NOT_APPLICABLE/DEFERRED.
• No unresolved MISSING or unqualified PARTIAL rows remain for this category.
• Relevant .NET tests pass locally and parity evidence is written into inventory notes.

Implementation Scope Inputs

Go Source Files

• golang/nats-server/server/raft.go

Go Test Files

• golang/nats-server/server/raft_test.go
• golang/nats-server/server/raft_helpers_test.go
• golang/nats-server/server/raft_chain_of_blocks_helpers_test.go

.NET Source Files

• src/NATS.Server/Raft/ (all 20 files)

.NET Test Files

• tests/NATS.Server.Tests/Raft/