# 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.