# Utilities & Other Gap Port Implementation Plan

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

**Goal:** Port all remaining `utilities-and-other` 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/utilities-and-other.md`
- Primary .NET Source Anchor: `src/NATS.Server/IO/OutboundBufferPool.cs`
- Primary .NET Test Anchor: `tests/NATS.Server.Tests/IO/`
- Full .NET test project: `tests/NATS.Server.Tests/NATS.Server.Tests.csproj`

## Task 1: Freeze Row-Level Backlog

**Files:**
- Modify: `gaps/utilities-and-other.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/IO/`
- 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/IO/OutboundBufferPool.cs`
- Modify: additional category files listed in `gaps/utilities-and-other.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/utilities-and-other.md`
- Modify: `gaps/utilities-and-other.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/utilities-and-other.md`
- Modify: `gaps/stillmissing.md`

**Step 1: Ensure final status correctness**
- Verify no unresolved `MISSING` rows remain for `utilities-and-other`.

**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 `utilities-and-other` 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/utilities-and-other.md` and `gaps/stillmissing.md` are fully synchronized.
