natsnet/docs/plans/2026-02-27-batch-7-opts-class-methods-reload-plan.md

Batch 7 (Opts Class Methods + Reload) Implementation Plan

For Codex: REQUIRED SUB-SKILL: Use executeplan to implement this plan task-by-task.

Goal: Implement and verify Batch 7 config-receiver and reload orchestration behavior from server/opts.go and server/reload.go (25 features, 63 tests) with evidence-backed status updates and zero stubs.

Architecture: Execute two feature groups (both <=20 features) in Go source order, then execute three test groups by mapped .NET class. Use strict per-feature and per-test verification loops, and promote statuses only when build and related tests prove behavior. Keep blocked items deferred with explicit reasons rather than stubbing.

Tech Stack: .NET 10, C# latest, xUnit 3, Shouldly, NSubstitute, PortTracker CLI, SQLite (porting.db)

Design doc: docs/plans/2026-02-27-batch-7-opts-class-methods-reload-design.md

---

Batch 7 Working Set

Batch facts:

• Batch ID: 7
• Features: 25
• Tests: 63
• Depends on: Batch 6
• Go files: golang/nats-server/server/opts.go, golang/nats-server/server/reload.go

Environment note:

• Use /usr/local/share/dotnet/dotnet for all dotnet commands in this workspace.

Feature groups (<=20 features each):

• F1 Config receiver + reload helper primitives (14): 2510,2511,2513,2514,2815,2816,2839,2873,2875,2877,2878,2886,2887,2888
• F2 Reload orchestration + server apply path (11): 2869,2872,2874,2876,2879,2880,2881,2882,2883,2884,2885

Test groups:

• T1 ServerOptions mapping (40): 2514,2517,2519,2520,2521,2522,2523,2525,2526,2527,2528,2529,2530,2531,2532,2533,2540,2541,2542,2544,2545,2546,2547,2549,2550,2553,2555,2556,2557,2560,2565,2566,2567,2569,2583,2588,2589,2590,2593,2597
• T2 Route/Leaf/Proxy mapping (18): 1897,1898,1908,1909,1932,1939,1943,2796,2797,2799,2800,2801,2802,2803,2804,2805,2806,2813
• T3 Cross-cutting reload regressions (5): 1893,2239,2372,2774,2904

---

MANDATORY VERIFICATION PROTOCOL

NON-NEGOTIABLE: No feature or test can be promoted without this evidence loop.

Per-Feature Verification Loop (REQUIRED)

For every feature ID:

1. Read mapping and exact Go location:

   /usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- feature show <feature-id> --db porting.db
   

2. Read referenced Go code in opts.go or reload.go.
3. Implement only that feature's behavior in C#.
4. Build immediately:

   /usr/local/share/dotnet/dotnet build dotnet/
   

5. Run related mapped tests (at least class-filtered) for the behavior touched.
6. Add feature ID to promotion candidate list only if build + related tests are green.

Stub Detection Check (REQUIRED)

Run after each feature sub-slice and each test class before status updates:

# Source and test stub markers
rg -n "NotImplementedException|TODO|PLACEHOLDER|throw new Exception\(\"not implemented\"\)" \
  dotnet/src/ZB.MOM.NatsNet.Server/ServerOptions*.cs \
  dotnet/src/ZB.MOM.NatsNet.Server/Config/*.cs \
  dotnet/src/ZB.MOM.NatsNet.Server/NatsServer*.cs \
  dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/*.cs

# Empty method bodies in touched C# files
rg -n "^\s*(public|private|internal|protected).+\)\s*\{\s*\}\s*$" \
  dotnet/src/ZB.MOM.NatsNet.Server/ServerOptions*.cs \
  dotnet/src/ZB.MOM.NatsNet.Server/Config/*.cs \
  dotnet/src/ZB.MOM.NatsNet.Server/NatsServer*.cs \
  dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/*.cs

If any match appears in code touched for Batch 7, do not promote status until fixed or explicitly deferred.

Build Gate (REQUIRED)

After each feature group (F1, F2):

/usr/local/share/dotnet/dotnet build dotnet/

Gate condition: build must succeed with 0 errors.

Test Gate (REQUIRED)

All related tests must pass before setting features to verified.

Suggested class gates:

# F1 related class gate
/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
  --filter "FullyQualifiedName~ImplBacklog.ServerOptionsTests|FullyQualifiedName~ImplBacklog.RouteHandlerTests|FullyQualifiedName~ImplBacklog.LeafNodeHandlerTests|FullyQualifiedName~ImplBacklog.LeafNodeProxyTests" \
  --verbosity normal

# F2 related class gate
/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
  --filter "FullyQualifiedName~ImplBacklog.ConfigReloaderTests|FullyQualifiedName~ImplBacklog.NatsServerTests|FullyQualifiedName~ImplBacklog.JwtProcessorTests|FullyQualifiedName~ImplBacklog.MqttHandlerTests|FullyQualifiedName~ImplBacklog.ConcurrencyTests1|FullyQualifiedName~ImplBacklog.RouteHandlerTests|FullyQualifiedName~ImplBacklog.LeafNodeHandlerTests" \
  --verbosity normal

Gate condition: Failed: 0.

Status Update Protocol (REQUIRED)

Rules:

• Use <=15 IDs per feature batch-update or test batch-update call.
• Evidence required for every promotion chunk:
  • feature/test IDs being promoted
  • latest build gate output
  • relevant test gate output
  • latest stub scan output
• Status progression:
  • Features: deferred/not_started -> stub -> complete -> verified
  • Tests: deferred/not_started -> stub -> verified (or stay deferred with reason)

Command templates:

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "<ids <=15>" --set-status <stub|complete|verified> --db porting.db --execute

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  test batch-update --ids "<ids <=15>" --set-status <stub|verified> --db porting.db --execute

If Roslyn audit blocks update:

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature update <id> --status <status> --db porting.db --override "evidence: <short reason>"

Checkpoint Protocol Between Tasks (REQUIRED)

After each task before moving to the next:

1. Full build:

   /usr/local/share/dotnet/dotnet build dotnet/
   

2. Full unit test suite:

   /usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --verbosity normal
   

3. Record summary counts (Passed, Failed, Skipped).
4. Commit task slice before continuing.

---

ANTI-STUB GUARDRAILS

Forbidden Patterns

The following are forbidden for Batch 7 feature and test work:

• throw new NotImplementedException(...)
• Empty mapped feature methods ({ }) or empty lambda bodies
• TODO / PLACEHOLDER used as unresolved behavior for mapped IDs
• Fake-positive tests (Assert.True(true), method-name string assertions, constant-only checks with no Act)
• Tests that do not invoke production code from ZB.MOM.NatsNet.Server.*

Hard Limits

• Max 20 features per feature group (already enforced: 14 and 11)
• Max 15 IDs per any batch status update command
• Max one feature-group promotion cycle at a time
• Mandatory build gate after each feature group
• Mandatory related-test gate before any verified feature promotion
• Mandatory checkpoint (full build + full test + commit) between tasks

If You Get Stuck (REQUIRED)

Do not stub. Do not fake-pass tests.

1. Keep blocked item deferred.
2. Add explicit blocker reason.
3. Continue with next unblocked item.

Commands:

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature update <id> --status deferred --db porting.db \
  --override "blocked: <specific unported dependency/runtime requirement>"

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  test update <id> --status deferred --db porting.db \
  --override "blocked: <specific unported dependency/runtime requirement>"

---

Task 1: Preflight and Batch Activation

Files:

• Modify: porting.db

Step 1: Verify dependency state (Batch 6)

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch show 6 --db porting.db

Expected: Batch 6 complete before starting Batch 7 implementation.

Step 2: Start Batch 7

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch start 7 --db porting.db

Step 3: Mark F1 features as stub (single chunk <=15)

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "2510,2511,2513,2514,2815,2816,2839,2873,2875,2877,2878,2886,2887,2888" \
  --set-status stub --db porting.db --execute

Step 4: Run checkpoint protocol and commit

---

Task 2: Implement Feature Group F1 (Config Receiver + Reload Helpers)

Files:

• Modify: dotnet/src/ZB.MOM.NatsNet.Server/ServerOptions.Methods.cs
• Modify: dotnet/src/ZB.MOM.NatsNet.Server/Config/ServerOptionsConfiguration.cs
• Modify: dotnet/src/ZB.MOM.NatsNet.Server/Config/ReloadOptions.cs
• Create (if needed): dotnet/src/ZB.MOM.NatsNet.Server/Config/ReloadDiffHelpers.cs
• Modify: porting.db

Step 1: Execute per-feature verification loop for each F1 ID

IDs: 2510,2511,2513,2514,2815,2816,2839,2873,2875,2877,2878,2886,2887,2888

Step 2: Run stub detection check on touched source and test files

Step 3: Run F1 build gate and F1 test gate

Step 4: Promote F1 features to complete (single chunk)

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "2510,2511,2513,2514,2815,2816,2839,2873,2875,2877,2878,2886,2887,2888" \
  --set-status complete --db porting.db --execute

Step 5: Promote F1 features to verified only if F1 test gate is green

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "2510,2511,2513,2514,2815,2816,2839,2873,2875,2877,2878,2886,2887,2888" \
  --set-status verified --db porting.db --execute

Step 6: Run checkpoint protocol and commit

---

Task 3: Implement Feature Group F2 (Server Reload Orchestration)

Files:

• Create: dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Reload.cs
• Modify: dotnet/src/ZB.MOM.NatsNet.Server/Config/ReloadOptions.cs
• Modify: dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.cs (only if field/property exposure is required)
• Modify: porting.db

Step 1: Mark F2 as stub

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "2869,2872,2874,2876,2879,2880,2881,2882,2883,2884,2885" \
  --set-status stub --db porting.db --execute

Step 2: Execute per-feature verification loop for each F2 ID

Step 3: Run stub detection check

Step 4: Run build gate and F2 test gate

Step 5: Promote F2 to complete

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "2869,2872,2874,2876,2879,2880,2881,2882,2883,2884,2885" \
  --set-status complete --db porting.db --execute

Step 6: Promote F2 to verified only with green F2 test gate

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "2869,2872,2874,2876,2879,2880,2881,2882,2883,2884,2885" \
  --set-status verified --db porting.db --execute

Step 7: Run checkpoint protocol and commit

---

Task 4: Implement Test Group T1 (ServerOptions Tests, 40 IDs)

Files:

• Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ServerOptionsTests.Impltests.cs
• Modify: porting.db

Step 1: Mark T1 IDs as stub in <=15 chunks

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  test batch-update --ids "2514,2517,2519,2520,2521,2522,2523,2525,2526,2527,2528,2529,2530,2531,2532" \
  --set-status stub --db porting.db --execute

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  test batch-update --ids "2533,2540,2541,2542,2544,2545,2546,2547,2549,2550,2553,2555,2556,2557,2560" \
  --set-status stub --db porting.db --execute

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  test batch-update --ids "2565,2566,2567,2569,2583,2588,2589,2590,2593,2597" \
  --set-status stub --db porting.db --execute

Step 2: For each T1 ID, run per-test loop (read Go test, write real Arrange/Act/Assert, run single test)

Step 3: Run class-level gate for ServerOptionsTests

/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
  --filter "FullyQualifiedName~ImplBacklog.ServerOptionsTests" --verbosity normal

Step 4: Run stub scan and reject any placeholder patterns

Step 5: Promote T1 IDs to verified in the same <=15 chunks only after class gate is green

Step 6: Run checkpoint protocol and commit

---

Task 5: Implement Test Group T2 (Route/Leaf/Proxy, 18 IDs)

Files:

• Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs
• Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeHandlerTests.Impltests.cs
• Create: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/LeafNodeProxyTests.Impltests.cs
• Modify: porting.db

Step 1: Mark T2 IDs as stub in <=15 chunks

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  test batch-update --ids "1897,1898,1908,1909,1932,1939,1943,2796,2797,2799,2800,2801,2802,2803,2804" \
  --set-status stub --db porting.db --execute

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  test batch-update --ids "2805,2806,2813" \
  --set-status stub --db porting.db --execute

Step 2: Execute per-test verification loop for each ID

Step 3: Run class gates

/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
  --filter "FullyQualifiedName~ImplBacklog.RouteHandlerTests|FullyQualifiedName~ImplBacklog.LeafNodeHandlerTests|FullyQualifiedName~ImplBacklog.LeafNodeProxyTests" \
  --verbosity normal

Step 4: Run stub scan on all three class files

Step 5: Promote T2 IDs to verified (same <=15 chunks) only when class gates pass

Step 6: Run checkpoint protocol and commit

---

Task 6: Implement Test Group T3 (Cross-Cutting, 5 IDs)

Files:

• Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConfigReloaderTests.Impltests.cs
• Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JwtProcessorTests.Impltests.cs
• Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MqttHandlerTests.Impltests.cs
• Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs
• Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/NatsServerTests.Impltests.cs
• Modify: porting.db

Step 1: Mark T3 IDs as stub

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  test batch-update --ids "1893,2239,2372,2774,2904" \
  --set-status stub --db porting.db --execute

Step 2: Execute per-test loop for each ID

Step 3: Run focused class gate

/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
  --filter "FullyQualifiedName~ImplBacklog.ConfigReloaderTests|FullyQualifiedName~ImplBacklog.JwtProcessorTests|FullyQualifiedName~ImplBacklog.MqttHandlerTests|FullyQualifiedName~ImplBacklog.ConcurrencyTests1|FullyQualifiedName~ImplBacklog.NatsServerTests" \
  --verbosity normal

Step 4: Run stub scan on touched files

Step 5: Promote T3 IDs to verified

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  test batch-update --ids "1893,2239,2372,2774,2904" \
  --set-status verified --db porting.db --execute

Step 6: Run checkpoint protocol and commit

---

Task 7: Final Batch 7 Closure Verification

Files:

• Modify: porting.db
• Generate: reports/current.md (via script)

Step 1: Full regression gate

/usr/local/share/dotnet/dotnet build dotnet/
/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --verbosity normal

Expected: build success and Failed: 0.

Step 2: Batch 7 global stub audit (source + test files touched in batch)

rg -n "NotImplementedException|TODO|PLACEHOLDER|Assert\.True\(true\)" \
  dotnet/src/ZB.MOM.NatsNet.Server/ServerOptions*.cs \
  dotnet/src/ZB.MOM.NatsNet.Server/Config/*.cs \
  dotnet/src/ZB.MOM.NatsNet.Server/NatsServer*.cs \
  dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/*.cs

Step 3: Confirm batch state and summary

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch show 7 --db porting.db
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db

Step 4: Complete batch when all items are verified/complete/n_a or explicitly deferred with reasons

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch complete 7 --db porting.db

Step 5: Generate report and commit

./reports/generate-report.sh
git add dotnet/src/ZB.MOM.NatsNet.Server dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog porting.db reports/
git commit -m "feat(batch7): implement opts class methods and reload with verified tests"

---

Notes for Execution

• Prefer behavior parity to Go intent over line-by-line translation.
• Keep reload behavior deterministic by preserving option application order.
• If any feature cannot be correctly completed because a required subsystem is unported, defer it with a concrete blocker reason instead of introducing a stub.