natsnet/docs/plans/2026-02-27-batch-6-opts-package-level-functions-design.md

Batch 6 (Opts Package-Level Functions) Design

Date: 2026-02-27
Scope: Design for Batch 6 planning only (67 features, 18 tests). No implementation in this document.

Context Snapshot

From batch show 6, batch list, and report summary:

• Batch ID: 6
• Name: Opts package-level functions
• Features: 67 (all currently deferred)
• Tests: 18 (all currently deferred)
• Dependency: Batch 4 (Logging)
• Go file: server/opts.go
• Primary .NET target: ServerOptions methods in dotnet/src/ZB.MOM.NatsNet.Server/
• Environment note: use /usr/local/share/dotnet/dotnet because dotnet is not on PATH

Current .NET baseline findings:

• ServerOptions.Methods.cs contains foundational option/clone/merge/default logic.
• Batch 6 mappings target many missing parse/configuration methods (TLS, auth, account parsing, websocket, MQTT, ConfigureOptions).
• Batch 6 mapped tests currently sit in ImplBacklog placeholder-style methods and are not evidence-quality verification.

Problem Statement

Batch 6 is a broad parser and option-bootstrap surface from server/opts.go. The risk is not only missing methods, but fake progress from placeholder tests or status updates without behavior evidence. The design must prioritize strict verification loops and explicit deferred handling instead of stubbing.

Constraints and Success Criteria

Constraints:

• Follow docs/standards/dotnet-standards.md (.NET 10, nullable, xUnit 3 + Shouldly + NSubstitute).
• Keep feature work in groups of at most ~20 IDs.
• Preserve dependency order: Batch 6 starts only after Batch 4 is complete.
• No fake tests, empty method bodies, or NotImplementedException placeholders.

Success criteria:

• All unblocked Batch 6 features are implemented with Go parity and verified evidence.
• Mapped Batch 6 tests are either real/passing or explicitly deferred with concrete runtime/dependency reason.
• Status transitions in porting.db are evidence-backed and chunked (max 15 IDs per batch update).

Approaches

Approach A: Single-file monolithic port in ServerOptions.Methods.cs

• Pros: minimal file churn.
• Cons: very high merge/review risk, hard to validate per-feature intent, encourages large unverifiable commits.

Approach B: Test-first by converting the 18 mapped tests only, then fill features

• Pros: quick visible test movement.
• Cons: mapped tests are mostly integration-heavy and do not cover all 67 feature methods; risks brittle or deferred-only progress.

Approach C (Recommended): Capability-sliced feature waves + mapped-test waves with strict gates

• Pros: manageable slices (<=20 features), deterministic checkpoints, clear evidence trail for status updates.
• Cons: more orchestration overhead.

Recommended Design

1. Feature Wave Decomposition (<=20 each)

Implement Batch 6 in four feature groups, ordered by opts.go flow:

• F1 Core config entry + cluster/gateway parse (16): 2502,2504,2505,2506,2507,2508,2509,2515,2516,2517,2519,2520,2521,2522,2523,2524
• F2 JetStream + leaf/gateway/TLS helpers (14): 2525,2526,2527,2528,2529,2530,2531,2532,2533,2534,2535,2536,2537,2538
• F3 Account + authorization parsing (17): 2539,2540,2541,2542,2543,2544,2545,2546,2547,2548,2549,2550,2551,2552,2553,2554,2555
• F4 Permission/TLS/websocket/MQTT/CLI configure (20): 2556,2557,2558,2559,2560,2561,2562,2563,2564,2565,2566,2567,2568,2569,2570,2571,2572,2573,2574,2580

2. Test Wave Decomposition (18 tests)

• T1 Options + reload + resolver wiring (4): 1832,2586,2587,2766
• T2 Leaf/route/websocket TLS behavior (8): 1918,1919,1929,1942,1950,2817,2821,3109
• T3 Monitoring + MQTT TLS behavior (6): 2108,2113,2114,2115,2166,2178

3. File Strategy

• Primary implementation target: dotnet/src/ZB.MOM.NatsNet.Server/ServerOptions.Methods.cs.
• If method volume becomes unreviewable, split into additional ServerOptions.*.cs partials by area (auth/accounts, TLS, transport parsing) without changing external API names.
• Primary mapped test targets:
  dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ServerOptionsTests.Impltests.cs,
  ConfigReloaderTests.Impltests.cs, JwtProcessorTests.Impltests.cs,
  LeafNodeHandlerTests.Impltests.cs, RouteHandlerTests.Impltests.cs,
  WebSocketHandlerTests.Impltests.cs, MonitoringHandlerTests.Impltests.cs,
  MqttHandlerTests.Impltests.cs.

4. Verification and Status Model

• Use per-feature loops (Go read -> C# implement -> build -> related tests).
• Use per-test loops for each mapped test ID.
• Promote statuses only after evidence gates; otherwise keep deferred with explicit reason.
• Prefer complete for implemented-but-not-fully-proven items; only set verified after all related tests pass.

5. Explicit Stuck Handling

• If blocked by missing infra/dependency (for example parser/token/runtime server harness), do not stub.
• Keep item deferred and attach concrete blocker note via --override.

Risks and Mitigations

1. Stub creep in ImplBacklog tests
   Mitigation: mandatory grep checks for placeholders and trivial assertion patterns.

2. Large parser surface causes regressions
   Mitigation: four bounded feature groups + build gate after each group.

3. Premature verified status updates
   Mitigation: max 15 IDs per update and required evidence log per chunk.

4. Dependency/infra blockers
   Mitigation: formal deferred-with-reason protocol; continue with unblocked IDs.

Approval-to-Plan Transition

This design selects Approach C and is ready for implementation planning with mandatory verification protocol and anti-stub guardrails for both features and tests.