# 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.