natsnet/docs/plans/2026-02-27-batch-18-server-core-implementation-plan.md

Batch 18 (Server Core) Implementation Plan

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

Goal: Implement and verify Batch 18 server-core behavior from server/server.go across 10 features and 8 tests without placeholder logic or fake-pass tests.

Architecture: Execute in two feature groups (6 + 4 IDs) mapped to NatsServer partial files, then run two test waves: real behavioral tests first, benchmark/race viability triage second. Promote tracker statuses only with build/test/stub-scan evidence.

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

---

I'm using writeplan to create the implementation plan.

Design doc: docs/plans/2026-02-27-batch-18-server-core-design.md

Batch Inputs

• Batch: 18 (Server Core)
• Depends on: 4, 16
• Features: 10
• Tests: 8
• Go source focus: golang/nats-server/server/server.go

Feature groups (max ~20 each):

• Group A (6): 2982,2987,3066,3068,3078,3119
• Group B (4): 3048,3088,3112,3118

Test groups:

• T1 (behavioral ports): 2111,2819,2897
• T2 (benchmark/race triage): 2167,2382,2467,2468,2481

If dotnet is not on PATH, use /usr/local/share/dotnet/dotnet in all commands below.

---

MANDATORY VERIFICATION PROTOCOL

NON-NEGOTIABLE: Every feature/test status change in Batch 18 must satisfy this protocol.

Per-Feature Verification Loop (REQUIRED for every feature ID)

1. Read tracker mapping and Go location:

   dotnet run --project tools/NatsNet.PortTracker -- feature show <FEATURE_ID> --db porting.db
   

2. Read the exact Go implementation in golang/nats-server/server/server.go at mapped lines.
3. Write behavior-faithful C# code in the mapped NatsServer partial file.
4. Build immediately:

   dotnet build dotnet/
   

5. Run related tests (targeted filter):

   dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
     --filter "FullyQualifiedName~<RelatedClassOrMethod>" --verbosity normal
   

6. Confirm tests were discovered (Passed > 0 when expected) and Failed: 0.
7. Only then add that feature ID to the verified-candidate list.

Stub Detection Check (REQUIRED after every feature/test group)

Run all scans before any complete or verified promotion:

# Feature-code stubs
grep -R -n -E "NotImplementedException|TODO|PLACEHOLDER" \
  dotnet/src/ZB.MOM.NatsNet.Server/NatsServer*.cs

# Empty method-body detector in feature files touched by Batch 18
grep -R -n -E "^[[:space:]]*(public|internal|private|protected)[^{;]*\)[[:space:]]*\{[[:space:]]*\}$" \
  dotnet/src/ZB.MOM.NatsNet.Server/NatsServer*.cs

# Test stubs + fake-pass patterns
grep -R -n -E "NotImplementedException|Assert\.True\(true\)|Assert\.Pass|// TODO|// PLACEHOLDER|ShouldContain\(\"Should\"\)|ShouldStartWith\(\"server/\"\)" \
  dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog

Any new hit in touched files blocks promotion until fixed or explicitly deferred.

Build Gate (REQUIRED after each feature group)

dotnet build dotnet/

Required: 0 errors.

Test Gate (REQUIRED before marking features verified)

All related tests for the feature group must pass before complete -> verified:

dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ServerTests" --verbosity normal
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ServerLifecycleStubFeaturesTests" --verbosity normal
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.MonitoringHandlerTests" --verbosity normal
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.RouteHandlerTests" --verbosity normal
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.NatsServerTests" --verbosity normal

Required: Failed: 0 and non-trivial execution for changed scenarios.

Status Update Protocol (REQUIRED)

1. Maximum 15 IDs per feature batch-update or test batch-update call.
2. Evidence required per update chunk:
   • Go source reviewed for each ID.
   • Build gate passed.
   • Related tests passed.
   • Stub scan clean.
3. No blind promotion:
   • Features: deferred -> stub -> complete -> verified.
   • Tests: deferred -> stub -> verified (or deferred/n_a with explicit reason).
4. If Roslyn audit disagrees, require explicit override reason.

Checkpoint Protocol Between Tasks (REQUIRED)

After each task (and before the next):

1. Full build:

   dotnet build dotnet/
   

2. Full unit-test pass:

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

3. Verify no new regressions.
4. Commit checkpoint:

   git add <touched-files> porting.db
   git commit -m "<checkpoint message>"
   

---

ANTI-STUB GUARDRAILS (NON-NEGOTIABLE)

Forbidden Patterns

Do not introduce or keep any of these in Batch 18 scope:

• throw new NotImplementedException(...)
• // TODO or // PLACEHOLDER in executable Batch 18 paths
• Empty method bodies ({ }) for mapped Batch 18 features
• Tests that only assert constants/labels (for example "...ShouldSucceed".ShouldContain("Should"))
• Tests that never execute target server behavior (no real Arrange/Act against NatsServer)
• Fake wrappers that ignore inputs and always return success values

Hard Limits

• Max ~20 feature IDs per implementation task group (Batch 18 uses 6 and 4)
• Max 15 IDs per status-update command
• No status promotion without clean stub scan + build gate + test gate
• No cross-group status updates until current group is fully verified/deferred
• Mandatory commit at each checkpoint

If You Get Stuck

1. Stop on the blocked item; do not add a stub workaround.
2. Do not write fake-pass tests or no-op implementations.
3. Mark the exact ID as deferred (or n_a for benchmark-only items) with specific reason:

   dotnet run --project tools/NatsNet.PortTracker -- \
     feature update <ID> --status deferred --db porting.db \
     --override "blocked: <specific infra/dependency reason>"
   

   dotnet run --project tools/NatsNet.PortTracker -- \
     test update <ID> --status deferred --db porting.db \
     --override "blocked: <specific infra/dependency reason>"
   

4. Continue with the next unblocked ID.

---

Task 1: Preflight and Batch Activation

Files:

• Modify: porting.db

Step 1: Confirm dependency readiness and batch contents

dotnet run --project tools/NatsNet.PortTracker -- batch show 18 --db porting.db
dotnet run --project tools/NatsNet.PortTracker -- batch ready --db porting.db

Step 2: Start batch

dotnet run --project tools/NatsNet.PortTracker -- batch start 18 --db porting.db

Step 3: Move Group A features to stub (<=15 IDs)

dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "2982,2987,3066,3068,3078,3119" \
  --set-status stub --db porting.db --execute

Step 4: Commit checkpoint

git add porting.db
git commit -m "chore(batch18): start batch and stage group-a features"

Task 2: Group A Features (6) - Compression/TLS/Monitoring/Goroutine Labels

Feature IDs: 2982,2987,3066,3068,3078,3119

Files:

• Modify: dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Init.cs
• Modify: dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Listeners.cs
• Modify: dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Lifecycle.cs
• Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ServerTests.cs
• Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MonitoringHandlerTests.Impltests.cs

Step 1: Add/extend failing tests for Group A behavior

Target behaviors:

• S2 writer-option mapping behavior (s2WriterOptions).
• TLS rejection log loop cadence and warning behavior.
• Monitoring TLS config clone + ClientAuth override.
• HTTPHandler returns non-null while monitor is active and null after shutdown.
• TLS handshake timeout closure path.
• Goroutine label helper invoked by task start path (or explicit helper test if direct validation is feasible).

Step 2: Run focused tests and confirm failures first

dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ServerTests" --verbosity normal
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.MonitoringHandlerTests" --verbosity normal

Step 3: Implement Group A methods with per-feature loop

For each of the 6 feature IDs: read Go -> implement -> build -> run related tests.

Step 4: Run mandatory stub detection + build gate + test gate

Use protocol commands above.

Step 5: Promote Group A feature statuses (complete, then verified)

dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "2982,2987,3066,3068,3078,3119" \
  --set-status complete --db porting.db --execute

dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "2982,2987,3066,3068,3078,3119" \
  --set-status verified --db porting.db --execute

Step 6: Checkpoint protocol + commit

git add dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Init.cs \
        dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Listeners.cs \
        dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Lifecycle.cs \
        dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ServerTests.cs \
        dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MonitoringHandlerTests.Impltests.cs \
        porting.db
git commit -m "feat(batch18): implement group-a server core helpers"

Task 3: Group B Features (4) - Accounts/Readiness/Introspection

Feature IDs: 3048,3088,3112,3118

Files:

• Modify: dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Accounts.cs
• Modify: dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Lifecycle.cs
• Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Server/ServerLifecycleStubFeaturesTests.cs
• Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs
• Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/NatsServerTests.Impltests.cs

Step 1: Write/extend failing tests for Group B behavior

Target behaviors:

• Account fetch path parity (fetchAccount wrapper/behavior alignment).
• Internal numRemotes path parity under lock.
• readyForConnections path parity for listener checks and timeout errors.
• String() / ToString() parity on server identity.

Step 2: Run focused tests and confirm failures first

dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ServerLifecycleStubFeaturesTests" --verbosity normal
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.RouteHandlerTests" --verbosity normal
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.NatsServerTests" --verbosity normal

Step 3: Implement Group B methods with per-feature loop

For each of the 4 feature IDs: read Go -> implement -> build -> run related tests.

Step 4: Run mandatory stub detection + build gate + test gate

Use protocol commands above.

Step 5: Promote Group B feature statuses (complete, then verified)

dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "3048,3088,3112,3118" \
  --set-status complete --db porting.db --execute

dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "3048,3088,3112,3118" \
  --set-status verified --db porting.db --execute

Step 6: Checkpoint protocol + commit

git add dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Accounts.cs \
        dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Lifecycle.cs \
        dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Server/ServerLifecycleStubFeaturesTests.cs \
        dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs \
        dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/NatsServerTests.Impltests.cs \
        porting.db
git commit -m "feat(batch18): implement group-b server core helpers"

Task 4: Test Group T1 (Behavioral Tests) - Verify 3 Tests

Test IDs: 2111,2819,2897

Files:

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

Step 1: For each test ID, read mapping + Go source and port behavior intent

dotnet run --project tools/NatsNet.PortTracker -- test show <TEST_ID> --db porting.db

Step 2: Run each test method individually (must execute and pass)

dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
  --filter "FullyQualifiedName~<MappedClass>.<MappedMethod>" --verbosity normal

Step 3: Run class-level validation for touched classes

dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.MonitoringHandlerTests" --verbosity normal
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.RouteHandlerTests" --verbosity normal
dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --filter "FullyQualifiedName~ImplBacklog.NatsServerTests" --verbosity normal

Step 4: Update T1 tests in one chunk (<=15 IDs)

dotnet run --project tools/NatsNet.PortTracker -- \
  test batch-update --ids "2111,2819,2897" --set-status verified --db porting.db --execute

Step 5: Checkpoint protocol + commit

git add dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MonitoringHandlerTests.Impltests.cs \
        dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/RouteHandlerTests.Impltests.cs \
        dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/NatsServerTests.Impltests.cs \
        porting.db
git commit -m "test(batch18): port behavioral batch-18 tests"

Task 5: Test Group T2 (Benchmark/Race Triage) - Resolve 5 Tests Without Stubs

Test IDs: 2167,2382,2467,2468,2481

Files:

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

Step 1: Evaluate each Go test for xUnit viability

• 2167 is a Go benchmark (BenchmarkXMQTT): classify as n_a unless a benchmark harness is explicitly introduced.
• Norace wrapper tests (2382,2467,2468,2481): verify whether meaningful deterministic unit assertions can be ported.

Step 2: For viable tests, implement and verify with single-test execution

dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
  --filter "FullyQualifiedName~ImplBacklog.ConcurrencyTests" --verbosity normal

Step 3: For non-viable tests, set deferred or n_a with concrete reasons

dotnet run --project tools/NatsNet.PortTracker -- \
  test update 2167 --status n_a --db porting.db \
  --override "BenchmarkXMQTT is benchmark-only and not an xUnit unit-test target"

(Repeat for remaining blocked IDs with specific blocker text.)

Step 4: Run stub scan and checkpoint protocol, then commit

git add dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/MqttExternalTests.Impltests.cs \
        dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests1.Impltests.cs \
        dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/ConcurrencyTests2.Impltests.cs \
        porting.db
git commit -m "test(batch18): triage benchmark and norace mapped tests"

Task 6: Final Batch 18 Verification and Closure

Files:

• Modify: porting.db
• Generate: reports/current.md

Step 1: Final full verification

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

Step 2: Batch-wide stub audit

grep -R -n -E "NotImplementedException|TODO|PLACEHOLDER|Assert\.True\(true\)|Assert\.Pass|ShouldContain\(\"Should\"\)" \
  dotnet/src/ZB.MOM.NatsNet.Server/NatsServer*.cs \
  dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog

Step 3: Validate batch status and close

dotnet run --project tools/NatsNet.PortTracker -- batch show 18 --db porting.db
dotnet run --project tools/NatsNet.PortTracker -- batch complete 18 --db porting.db

Step 4: Refresh reports and final commit

./reports/generate-report.sh
git add porting.db reports/
git commit -m "chore(batch18): complete server-core batch with verified evidence"