# Protocol Full Parity Design

**Date:** 2026-02-25  
**Category:** `protocol`  
**Gap Inventory:** `gaps/protocol.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`: 48
- `PARTIAL`: 8
- `PORTED`: 15
- `NOT_APPLICABLE`: 12
- `DEFERRED`: 0
- **Open parity work items:** 56

## Approaches Considered
1. **Symbol-first closure (Recommended):** execute directly against each `MISSING` and `PARTIAL` row in `gaps/protocol.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/protocol.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/protocol.md` and `gaps/stillmissing.md` after each closure batch.

### Data Flow
1. Read one `MISSING` or `PARTIAL` row from `gaps/protocol.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/parser.go`
- `golang/nats-server/server/proto.go`
- `golang/nats-server/server/const.go`

### Go Test Files
- `golang/nats-server/server/parser_test.go`
- `golang/nats-server/server/parser_fuzz_test.go`
- `golang/nats-server/server/server_fuzz_test.go`
- `golang/nats-server/server/subject_fuzz_test.go`
- `golang/nats-server/server/split_test.go`

### .NET Source Files
- `src/NATS.Server/Protocol/NatsParser.cs`
- `src/NATS.Server/Protocol/NatsProtocol.cs`
- `src/NATS.Server/Protocol/NatsHeaderParser.cs`
- `src/NATS.Server/Protocol/ClientCommandMatrix.cs`
- `src/NATS.Server/Protocol/MessageTraceContext.cs`
- `src/NATS.Server/Protocol/ProxyProtocol.cs`

### .NET Test Files
- `tests/NATS.Server.Tests/Protocol/`
