Add batch plans for batches 23-30 (rounds 12-15)

Generated design docs and implementation plans via Codex for: - Batch 23: Routes - Batch 24: Leaf Nodes - Batch 25: Gateways - Batch 26: WebSocket - Batch 27: JetStream Core - Batch 28: JetStream API - Batch 29: JetStream Batching - Batch 30: Raft Part 1 All plans include mandatory verification protocol and anti-stub guardrails. Updated batches.md with file paths and planned status.
2026-02-27 16:33:10 -05:00
parent dc3e162608
commit c05d93618e
19 changed files with 5896 additions and 9 deletions
--- a/docs/plans/2026-02-27-batch-23-routes-design.md
+++ b/docs/plans/2026-02-27-batch-23-routes-design.md
@@ -0,0 +1,146 @@
+# Batch 23 Routes Design
+
+**Date:** 2026-02-27  
+**Batch:** 23 (`Routes`)  
+**Scope:** Design only. No implementation in this document.
+
+## Problem
+
+Batch 23 ports NATS route/cluster behavior from `golang/nats-server/server/route.go` into .NET.
+
+- Features: `52` (currently `deferred`)
+- Tests: `5` (currently `deferred`)
+- Dependencies: batches `16`, `18`
+- Go source: `server/route.go`
+- Batch status: `pending`
+
+This batch is the route control plane: route connect negotiation, route INFO gossip, per-account route subscriptions, route pooling, route lifecycle, and compression negotiation.
+
+## Context Findings
+
+Collected with:
+
+- `dotnet run --project tools/NatsNet.PortTracker -- batch show 23 --db porting.db`
+- `dotnet run --project tools/NatsNet.PortTracker -- batch list --db porting.db`
+- `dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db`
+
+Key findings:
+
+- Most Batch 23 methods do not yet exist in .NET runtime code.
+- Existing route surface in .NET is mostly type definitions (`Routes/RouteTypes.cs`) and some route-adjacent stubs in `NatsServer.Lifecycle.cs`.
+- The 5 mapped tests are all in `RouteHandlerTests` and currently deferred.
+- Existing `ProtocolParserTests` and `ServerTests` already cover route-adjacent parser/compression helpers and should be part of the feature verification gate.
+
+## Constraints and Success Criteria
+
+Constraints:
+
+- Follow `.NET 10` and project standards (`xUnit 3`, `Shouldly`, `NSubstitute`, no FluentAssertions/Moq).
+- Keep implementation idiomatic C# while preserving Go behavior semantics.
+- No placeholder implementations or fake-pass tests.
+- Feature groups must be <= ~20 features.
+- Batch status changes require evidence and guarded update cadence.
+
+Success criteria:
+
+- All 52 Batch 23 features are implemented and promoted with evidence (`deferred -> stub -> complete -> verified`) or explicitly deferred with blocker reason.
+- All 5 mapped Batch 23 tests are real behavioral tests and passing.
+- Route-related regression gates pass (`ProtocolParserTests`, `ServerTests`, lifecycle route tests, and mapped route ImplBacklog tests).
+
+## Approaches
+
+### Approach A: Single large route partial
+
+Implement all route behavior in one large `NatsServer.Routes.cs` + one `ClientConnection.Routes.cs` file.
+
+Trade-offs:
+
+- Pros: fewer files.
+- Cons: very large diff, difficult review, high regression risk, weak checkpointing.
+
+### Approach B (Recommended): Domain-segmented route partials
+
+Split route implementation into bounded domains aligned with `route.go` sections and Batch 23 grouping.
+
+Trade-offs:
+
+- Pros: clear ownership boundaries, strong per-group build/test gates, easier status evidence, lower merge risk.
+- Cons: more files and more coordination.
+
+### Approach C: Tests-first for all 5 mapped tests before feature work
+
+Rewrite all five mapped tests first, then implement features until tests pass.
+
+Trade-offs:
+
+- Pros: immediate test signal.
+- Cons: only 5 mapped tests under-cover 52 features, so this risks false confidence without strict per-feature verification.
+
+## Recommended Design
+
+Use **Approach B**.
+
+### Architecture
+
+Organize Batch 23 into three feature domains:
+
+1. Route protocol parsing and permission handling (inbound route msgs, account sub/unsub, permission checks, route info processing)
+2. Route subscription propagation and route creation pipeline (remote sub/unsub map operations, protocol emission, route object creation)
+3. Route lifecycle and cluster connectivity (start routing, reconnect/validate routes, duplicate handling, gossip/implicit route handling, route iteration helpers)
+
+Mapped tests are executed after feature groups, with additional regression gates from parser/server test classes before `complete -> verified` promotion.
+
+### Proposed File Map
+
+Primary production files:
+
+- Create: `dotnet/src/ZB.MOM.NatsNet.Server/ClientConnection.Routes.cs`
+- Create: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Routes.InfoAndPerms.cs`
+- Create: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Routes.Subscriptions.cs`
+- Create: `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Routes.Connections.cs`
+- Create: `dotnet/src/ZB.MOM.NatsNet.Server/Routes/RouteHandler.cs`
+- Modify (as needed): `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Lifecycle.cs`
+- Modify (as needed): `dotnet/src/ZB.MOM.NatsNet.Server/Protocol/IProtocolHandler.cs`
+- Modify (as needed): `dotnet/src/ZB.MOM.NatsNet.Server/Protocol/ProtocolParser.cs`
+- Modify (as needed): `dotnet/src/ZB.MOM.NatsNet.Server/Routes/RouteTypes.cs`
+
+Primary mapped test files:
+
+- Modify: `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs`
+
+Related regression test files:
+
+- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Protocol/ProtocolParserTests.cs`
+- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ServerTests.cs`
+- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Server/ServerLifecycleStubFeaturesTests.cs`
+
+### Data and Control Flow
+
+- Route connection establishment: connect -> route CONNECT/INFO exchange -> route registration -> sub interest sync.
+- Route message path: parse routed protocol args -> permission checks -> route/local interest updates -> inbound delivery handling.
+- Route topology updates: implicit route processing + forwarding new route info to known remotes + duplicate-route handling.
+
+### Error Handling Strategy
+
+- Mirror Go error semantics for parse and negotiation failures (return error / close connection path).
+- Use explicit guard clauses for malformed protocols and invalid route state transitions.
+- Keep blocked infrastructure behavior deferred with explicit reason instead of stubs.
+
+### Verification Strategy
+
+- Per-feature loop: read Go implementation, implement minimum C# behavior, build, run smallest related tests, record evidence.
+- Per-group gates: mandatory stub scan, build gate, targeted test gate.
+- Pre-verify gate: all related route test classes and mapped tests must pass before promoting any Batch 23 feature to `verified`.
+
+### Risks and Mitigations
+
+- Risk: Route lifecycle races/regressions due lock-sensitive logic.
+  - Mitigation: keep route iteration/removal code in focused partials; include lifecycle regression tests in every gate.
+- Risk: Placeholder test ports in `ImplBacklog` produce false green.
+  - Mitigation: explicit anti-stub scans and assertion quality checks before status updates.
+- Risk: Large route.go surface causes drift in status updates.
+  - Mitigation: strict ID chunking (<=15 per update) and evidence ledger per update.
+
+## Design Approval Basis
+
+This design is derived from the explicit request for Batch 23 planning, mandatory verification protocol parity with Batch 0, anti-stub guardrails, and grouped execution without implementation.