docs: add full-repo remaining parity design

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

@@ -0,0 +1,159 @@
+# 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.