diff --git a/docs/plans/2026-02-23-full-repo-remaining-parity-design.md b/docs/plans/2026-02-23-full-repo-remaining-parity-design.md new file mode 100644 index 0000000..71fb0bd --- /dev/null +++ b/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.