natsdotnet/docs/plans/2026-02-23-nats-post-strict-full-go-parity-design.md

NATS Post-Strict Full Go Parity Design

Date: 2026-02-23
Status: Approved
Scope: Identify and close all remaining NATS functionality/features versus local Go HEAD (golang/nats-server/server) using behavior-level parity with test evidence.

1. Architecture and Scope Boundary

Parity model

Each capability is considered complete only when all of the following are true:

1. Behavior
   Observable .NET runtime behavior matches the Go contract.

2. Tests
   Positive and edge/failure tests exist and fail on regression.

3. Docs
   differences.md and parity artifacts reflect verified behavior state.

Scope rule

This cycle is not constrained by existing parity-table status values. Residual behavior differences inferred from code depth, runtime paths, and subsystem contracts are in scope even when rows are currently marked Y.

Execution waves

1. Protocol/inter-server/account delivery semantics
2. MQTT full protocol/runtime semantics
3. JetStream runtime/state-machine semantics
4. RAFT/cluster governance + storage durability semantics
5. Operational/config/runtime drift closure and docs synchronization

Completion gate

Done is defined as feature-by-feature .NET behavioral parity evidence (targeted + full suite), not mandatory direct Go suite equivalence.

2. Component Plan and Remaining Capability Groups

A. Core protocol and inter-server semantics

Primary files:

• src/NATS.Server/NatsServer.cs
• src/NATS.Server/Routes/*
• src/NATS.Server/Gateways/*
• src/NATS.Server/LeafNodes/*
• src/NATS.Server/Subscriptions/SubList.cs

Remaining group:

• deep account-aware forwarding semantics
• advanced interest/topology behavior beyond baseline frame propagation

B. MQTT full parity

Primary files:

• src/NATS.Server/Mqtt/*
• src/NATS.Server/MqttOptions.cs
• integration points in auth/config/server startup paths

Remaining group:

• behavior depth still below Go MQTT subsystem semantics despite packet/QoS/session/auth baseline
• requires broader protocol/runtime contract coverage

C. JetStream runtime/service depth

Primary files:

• src/NATS.Server/JetStream/JetStreamService.cs
• src/NATS.Server/JetStream/StreamManager.cs
• src/NATS.Server/JetStream/ConsumerManager.cs
• src/NATS.Server/JetStream/Consumers/*
• src/NATS.Server/JetStream/MirrorSource/*

Remaining group:

• simplified manager/service behavior relative to Go stream/consumer runtime depth
• needs stricter long-run invariants and edge-state handling

D. RAFT, JetStream governance, and storage

Primary files:

• src/NATS.Server/Raft/*
• src/NATS.Server/JetStream/Cluster/*
• src/NATS.Server/JetStream/Storage/*

Remaining group:

• broader convergence/placement/membership semantics
• deeper durability and consistency guarantees under restart/failure scenarios

E. Operational/config/runtime parity

Primary files:

• src/NATS.Server/NatsOptions.cs
• src/NATS.Server/Configuration/*
• src/NATS.Server/Monitoring/*
• src/NATS.Server/Events/*

Remaining group:

• config surface vs runtime behavior depth mismatches
• monitoring/operations parity consistency closure

F. Evidence/documentation

Primary files:

• differences.md
• docs/plans/2026-02-23-nats-strict-full-go-parity-map.md
• docs/plans/2026-02-23-jetstream-remaining-parity-map.md
• docs/plans/2026-02-23-jetstream-remaining-parity-verification.md

Remaining group:

• synchronize claims with measurable behavior and test evidence

3. Data Flow and Behavioral Contracts

1. Inter-server routing contract

• account-scoped interest and delivery must remain correct under churn/reconnect/replay
• transport markers/remaps remain internal and reversible

2. MQTT protocol/runtime contract

• packet framing/encoding correctness and session/QoS/ack state-machine consistency
• auth/tls/account mapping fail closed on invalid state

3. JetStream stream/consumer contract

• retention mode semantics diverge at runtime behavior
• deterministic cursor/ack/redelivery/backoff/replay/flow transitions
• mirror/source behavior respects account/filter/transform contracts

4. RAFT/governance/storage contract

• quorum-gated commit visibility, term safety, and convergence
• snapshot/membership/placement semantics reflect committed state
• storage invariants hold across prune/recovery/restart paths

5. Documentation contract

• no closure claim without behavior+test evidence
• deferred items must be explicit and evidence-backed

4. Error Handling, Testing Strategy, and Completion Gates

Error handling

1. Preserve protocol-specific error semantics (NATS, MQTT, JetStream).
2. Fail closed on account/auth/consensus violations.
3. Avoid partial state mutation on multi-step cross-subsystem operations.

Testing strategy

1. Test-first for every capability.
2. Require happy-path + edge/failure coverage per capability.
3. Use integration tests for inter-server, MQTT runtime, RAFT/cluster, and restart durability semantics.
4. Use focused unit tests for deterministic parser/state primitives.

Completion gates

1. Capability closes only when Behavior + Tests + Docs are complete.
2. Focused wave suites pass and full suite passes:

• dotnet test -v minimal

3. Documentation artifacts are synchronized to verified runtime behavior.