natsdotnet/docs/plans/2026-02-25-gap-port-events-plan.md

Events Gap Port Implementation Plan

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

Goal: Port all remaining events gap inventory items to achieve full behavior parity with Go.

Architecture: Use the category gap inventory as the execution backlog. Drive work row-by-row from MISSING and PARTIAL toward PORTED, with test-first validation and explicit parity evidence in notes.

Tech Stack: .NET 10, C#, xUnit, existing NATS.Server runtime modules, Go NATS server reference source.

---

Category Inputs

• Gap Inventory: gaps/events.md
• Primary .NET Source Anchor: src/NATS.Server/Events/ (all files)
• Primary .NET Test Anchor: tests/NATS.Server.Tests/Events/
• Full .NET test project: tests/NATS.Server.Tests/NATS.Server.Tests.csproj

Task 1: Freeze Row-Level Backlog

Files:

• Modify: gaps/events.md

Step 1: Normalize open rows into an execution queue

• Split all MISSING and PARTIAL rows into ranked batches (highest runtime impact first).

Step 2: Record acceptance criteria per row

• For each row, define exact behavioral parity checks (inputs, outputs, error paths, timing/concurrency expectations).

Step 3: Save queue annotations in notes

• Add short execution-order markers in notes without changing status yet.

Task 2: Write Failing Tests for Batch 1

Files:

• Modify: tests/NATS.Server.Tests/Events/
• Test: tests/NATS.Server.Tests/NATS.Server.Tests.csproj

Step 1: Add failing tests for first open row batch

• Create tests that reproduce the exact missing/partial Go behavior.

Step 2: Run tests to confirm failure

• Run: dotnet test tests/NATS.Server.Tests/NATS.Server.Tests.csproj -c Release
• Expected: FAIL in newly added tests only.

Task 3: Implement Minimal Parity for Batch 1

Files:

• Modify: src/NATS.Server/Events/ (all files)
• Modify: additional category files listed in gaps/events.md

Step 1: Implement minimal code to satisfy failing tests

• Mirror Go semantics for parsing, state transitions, limits, and side-effects required by the targeted rows.

Step 2: Re-run tests for validation

• Run: dotnet test tests/NATS.Server.Tests/NATS.Server.Tests.csproj -c Release
• Expected: PASS for batch-1 tests; no new regressions.

Task 4: Close Remaining Batches Iteratively

Files:

• Modify: category .NET source and test files referenced in gaps/events.md
• Modify: gaps/events.md

Step 1: Repeat test-first cycle for each remaining batch

• Add failing tests, implement minimal parity, then verify pass.

Step 2: Update inventory status immediately after each closure

• Move rows to PORTED with exact .NET file:line references.
• Keep PARTIAL only if explicit residual behavior remains.

Task 5: Cross-Module Regression and Hardening

Files:

• Test: tests/NATS.Server.Tests/NATS.Server.Tests.csproj

Step 1: Run full regression suite

• Run: dotnet test tests/NATS.Server.Tests/NATS.Server.Tests.csproj -c Release
• Expected: PASS.

Step 2: Add edge-case tests discovered during regression

• Capture any newly discovered divergence from Go and close it before completion.

Task 6: Finalize Parity Bookkeeping

Files:

• Modify: gaps/events.md
• Modify: gaps/stillmissing.md

Step 1: Ensure final status correctness

• Verify no unresolved MISSING rows remain for events.

Step 2: Refresh LOC and percentage bookkeeping

• Recount category LOC and update summary rows in gaps/stillmissing.md.

Step 3: Add concise changelog entry

• Record date, completed parity areas, and any justified deferred items.

Completion Checklist

• All prioritized events rows are PORTED or explicitly justified as NOT_APPLICABLE/DEFERRED.
• New/updated tests demonstrate parity for all previously open rows.
• dotnet test tests/NATS.Server.Tests/NATS.Server.Tests.csproj -c Release passes.
• gaps/events.md and gaps/stillmissing.md are fully synchronized.