natsdotnet/docs/plans/2026-02-23-full-repo-remaining-parity-design.md

Full-Repo Remaining Parity Design

Date: 2026-02-23
Status: Approved
Scope: Close all remaining Baseline / N / Stub rows in differences.md using strict behavioral parity criteria with test-backed evidence.

1. Architecture and Scope Boundary

Parity control model

Parity closure in this cycle uses a row-level truth matrix with three independent states per unresolved row:

1. Behavior

• Go-contract behavior is implemented (not just helper hooks or placeholders).

2. Tests

• Contract-positive and negative/edge tests exist and fail if behavior regresses to baseline.

3. Docs

• differences.md row status matches verified behavior/test state.

Rows move to Y only when Behavior + Tests + Docs are all complete.

Execution ordering

1. Core protocol, transport, and sublist semantics.
2. Auth and monitoring rows.
3. JetStream runtime policy semantics.
4. JetStream storage, RAFT, and JetStream clustering semantics.
5. Documentation and evidence synchronization.

Scope note

This cycle intentionally covers full-repo unresolved rows, not JetStream-only, because remaining JetStream closure depends on transport/protocol/subscription/runtime correctness and docs currently contain summary/table inconsistencies.

2. Component Plan

A. Protocol and transport parity

Primary files:

• src/NATS.Server/NatsServer.cs
• src/NATS.Server/NatsClient.cs
• src/NATS.Server/Protocol/NatsParser.cs
• src/NATS.Server/Protocol/ClientCommandMatrix.cs
• src/NATS.Server/Routes/RouteConnection.cs
• src/NATS.Server/Routes/RouteManager.cs
• src/NATS.Server/Gateways/GatewayConnection.cs
• src/NATS.Server/Gateways/GatewayManager.cs
• src/NATS.Server/LeafNodes/LeafConnection.cs
• src/NATS.Server/LeafNodes/LeafNodeManager.cs

Target rows:

• Inter-server op semantics and routing contracts still marked baseline or missing.
• Gateway/leaf advanced semantics beyond handshake-level support.
• Route/gateway/leaf account-aware interest and delivery behavior.

B. SubList and subscription parity

Primary files:

• src/NATS.Server/Subscriptions/SubList.cs
• src/NATS.Server/Subscriptions/RemoteSubscription.cs
• src/NATS.Server/Subscriptions/Subscription.cs

Target rows:

• Notification/interest-change hooks.
• Local/remote filtering and queue-weight behavior.
• MatchBytes and cache/fanout parity behavior.

C. Auth and monitoring parity

Primary files:

• src/NATS.Server/Auth/*
• src/NATS.Server/Monitoring/ConnzHandler.cs
• src/NATS.Server/Monitoring/VarzHandler.cs
• src/NATS.Server/Monitoring/* response models

Target rows:

• Missing auth extension points (custom/external/proxy).
• Remaining connz/varz filters and fields.

D. JetStream runtime parity

Primary files:

• src/NATS.Server/JetStream/StreamManager.cs
• src/NATS.Server/JetStream/ConsumerManager.cs
• src/NATS.Server/JetStream/Consumers/*
• src/NATS.Server/JetStream/Publish/*
• src/NATS.Server/JetStream/Api/Handlers/*
• src/NATS.Server/JetStream/Validation/JetStreamConfigValidator.cs

Target rows:

• Stream retention/maxage/maxmsgsper/maxmsgsize and stream feature toggles.
• Consumer ack/backoff/delivery/replay/flow/rate semantics.
• Mirror/source advanced behavior and cross-account semantics.

E. Storage, RAFT, and JetStream cluster parity

Primary files:

• src/NATS.Server/JetStream/Storage/*
• src/NATS.Server/Raft/*
• src/NATS.Server/JetStream/Cluster/*
• src/NATS.Server/NatsServer.cs integration points

Target rows:

• FileStore behavior gaps (layout/index/ttl/compression/encryption).
• RAFT behavior gaps (heartbeat/next-index/snapshot transfer/membership/transport semantics).
• JetStream meta-group and replica-group behavioral gaps.

F. Evidence and documentation parity

Primary files:

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

Target:

• Remove summary/table drift and keep row status tied to behavior and tests.

3. Data Flow and Behavioral Contracts

1. Truth-matrix contract

• Every unresolved row is tracked as Behavior/Test/Docs until closure.
• Summary statements never override unresolved table rows.

2. Transport contract

• Inter-server propagation preserves account scope and message semantics end-to-end.
• Remote delivery resolves against correct account state, not global-only shortcuts.
• Gateway reply remap and leaf loop markers stay transparent to client-visible semantics.

3. SubList contract

• Local interest and remote interest behavior are explicitly separated and account-aware.
• Queue weights and remote subscriptions influence deterministic routing decisions.
• Cache and match behavior remain correct under concurrent mutate/read operations.

4. Auth and monitoring contract

• New auth extension points must preserve existing permission and revocation safety.
• connz/varz parity fields reflect live data and match expected filter/sort semantics.

5. JetStream runtime contract

• Stream policy semantics are enforced in runtime operations, not only parse-time.
• Consumer state transitions are deterministic across pull/push and redelivery flows.
• Mirror/source behavior includes mapping and cross-account rules.

6. Storage/RAFT/cluster contract

• Store recovery and TTL/index semantics are deterministic.
• RAFT behavior is consensus-driven (not placeholder-only hooks).
• JetStream cluster governance behavior depends on effective state transitions.

4. Error Handling, Test Strategy, and Completion Criteria

Error handling

1. Preserve protocol-specific and JetStream-specific error contracts.
2. Fail closed on remap/loop/account-authorization anomalies.
3. Avoid partial state mutation on cross-node failures.

Test strategy

1. Each unresolved row gets positive + negative/edge coverage.
2. Multi-node/network semantics require integration tests, not helper-only tests.
3. Parity closure tests must inspect unresolved row status and supporting evidence, not only summary text.

Completion criteria

1. All in-scope unresolved rows are either:

• moved to Y with evidence, or
• explicitly blocked with concrete technical rationale and failing evidence.

2. Focused suites pass for protocol/transport/sublist/auth/monitoring/jetstream/raft layers.
3. Full suite passes:

• dotnet test -v minimal

4. differences.md, parity map, and verification report are synchronized to actual behavior and tests.