natsnet/docs/plans/2026-02-27-feature-status-audit-plan.md

# Feature Status Audit Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:executing-plans to implement this plan task-by-task.

**Goal:** Classify 3394 features currently marked `unknown` into the correct status (`verified`, `stub`, `n_a`, or `deferred`) by inspecting .NET source code against Go feature specifications.

**Architecture:** Process features in sequential batches of 50. Each batch: fetch 50 unknown features via PortTracker CLI, inspect the corresponding .NET source files, classify each feature, dry-run the batch updates, then execute. Repeat until zero unknown features remain.

**Tech Stack:** PortTracker CLI (`dotnet run --project tools/NatsNet.PortTracker`), .NET source at `dotnet/src/ZB.MOM.NatsNet.Server/`

**Design doc:** `docs/plans/2026-02-27-feature-status-audit-design.md`

---

## Important Rules (Read Before Every Task)

1. **ALWAYS dry-run before executing** — no exceptions. Every `batch-update` command must be run WITHOUT `--execute` first to preview.
2. **NEVER use direct SQL** (`sqlite3`) — use the PortTracker CLI exclusively for all database operations.
3. **Process exactly 50 per batch** (or fewer if fewer remain in the final batch).
4. **Report classification breakdown** after each batch (e.g. "Batch 3: 12 verified, 30 stub, 3 n_a, 5 deferred").

## Classification Criteria Reference

| Status | Criteria |
|--------|----------|
| `verified` | .NET method exists with non-trivial logic that matches the Go implementation's behavior |
| `stub` | .NET method exists but is `throw new NotImplementedException()`, empty, or only **partially** implemented (has structure but missing significant logic) |
| `n_a` | Go feature doesn't apply to .NET — .NET uses a different approach (e.g. Go logging → .NET uses `Microsoft.Extensions.Logging`) |
| `deferred` | .NET method doesn't exist at all, or classification requires the server running end-to-end |

## Key .NET Source Locations

When looking for a `dotnet_class`, search in these directories:

```
dotnet/src/ZB.MOM.NatsNet.Server/
  Accounts/          — Account, AccountResolver, DirJwtStore, AccountTypes
  Auth/              — AuthHandler, JwtProcessor, CipherSuites, AuthTypes
  Config/            — ReloadOptions, ServerOptionsConfiguration, NatsJsonConverters
  Events/            — EventTypes
  Gateway/           — GatewayTypes
  Internal/          — Subscription, WaitGroup, ClosedRingBuffer, RateCounter, DataStructures/
  JetStream/         — MemStore, ConsumerMemStore, FileStore, FileStoreTypes, MessageBlock
                       JetStreamTypes, JetStreamApiTypes, JetStreamErrors, JetStreamVersioning
                       NatsStream, NatsConsumer, RaftTypes, JetStreamClusterTypes
  LeafNode/          — LeafNodeTypes
  MessageTrace/      — MsgTraceTypes
  Monitor/           — MonitorTypes, MonitorSortOptions
  Mqtt/              — MqttConstants, MqttTypes, MqttHandler
  Protocol/          — ParserTypes, ProtocolParser, ProxyProtocol
  Routes/            — RouteTypes
  WebSocket/         — WebSocketConstants, WebSocketTypes
  NatsServer.cs, NatsServer.Auth.cs, NatsServer.Signals.cs, NatsServer.Init.cs
  NatsServer.Accounts.cs, NatsServer.Lifecycle.cs, NatsServer.Listeners.cs
  ClientConnection.cs, ClientTypes.cs, NatsMessageHeaders.cs
```

---

### Task 0: Verify starting state and PortTracker commands

**Files:** None — verification only.

**Step 1: Check how many unknown features exist**

```bash
dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status unknown --db porting.db
```

Expected: Output shows ~3394 features. Note the total count at the bottom.

**Step 2: Verify batch-update dry-run works**

```bash
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids 150-152 --set-status verified --db porting.db
```

Expected: Preview output showing 3 features. Should say "Would affect 3 items:" and "Add --execute to apply these changes." Do NOT execute — this is just confirming the tool works.

**Step 3: Record the starting count**

Note the total unknown count. This is your baseline. After all batches complete, the count should be 0.

---

### Task N (repeat for N=1 through 68): Process batch of 50 unknown features

> **This task is a template.** Repeat it until zero unknown features remain. Each execution processes the next 50.

**Files:** None — classification only, no code changes.

**Step 1: Fetch the next 50 unknown features**

```bash
dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status unknown --db porting.db
```

From the output, take the **first 50 feature IDs**. Note the `dotnet_class` and `dotnet_method` columns for each.

**Step 2: For each feature, inspect the .NET implementation**

For each of the 50 features:

1. **Find the .NET source file** — use `Grep` to search for the class:
   ```
   Grep pattern: "class {dotnet_class}" path: dotnet/src/ZB.MOM.NatsNet.Server/
   ```

2. **Find the method** — search within that file for the method name:
   ```
   Grep pattern: "{dotnet_method}" path: {the file found above}
   ```

3. **Read the method body** — use `Read` to view the method implementation.

4. **Classify the feature:**
   - If the method has real, non-trivial logic matching the Go behavior → `verified`
   - If the method is `throw new NotImplementedException()`, empty, or only partially there → `stub`
   - If the Go feature has a .NET-native replacement (e.g., Go's custom logging → `Microsoft.Extensions.Logging`, Go's `sync.Mutex` → C#'s `Lock`) → `n_a`
   - If the method doesn't exist in the .NET codebase at all → `deferred`

**Efficiency tip:** Features from the same `dotnet_class` should be inspected together — read the .NET file once and classify all features from that class in the batch.

**Step 3: Group IDs by classification result**

After inspecting all 50, organize the IDs into groups:

```
verified_ids: 2068,2069,2070,2071,...
stub_ids: 2080,2081,...
n_a_ids: 2090,...
deferred_ids: 2095,2096,...
```

**Step 4: Dry-run each group (MANDATORY — DO NOT SKIP)**

Run the dry-run for EACH status group. Review the output carefully.

```bash
# Dry-run verified
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {verified_ids} --set-status verified --db porting.db

# Dry-run stub
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {stub_ids} --set-status stub --db porting.db

# Dry-run n_a (include reason in notes)
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {n_a_ids} --set-status n_a --set-notes "{reason}" --db porting.db

# Dry-run deferred
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {deferred_ids} --set-status deferred --db porting.db
```

Check that:
- The feature names in the preview match what you inspected
- The count per group adds up to 50 (or the batch size)
- No unexpected features appear

**Step 5: Execute each group**

Only after verifying ALL dry-runs look correct:

```bash
# Execute verified
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {verified_ids} --set-status verified --execute --db porting.db

# Execute stub
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {stub_ids} --set-status stub --execute --db porting.db

# Execute n_a (with notes)
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {n_a_ids} --set-status n_a --set-notes "{reason}" --execute --db porting.db

# Execute deferred
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {deferred_ids} --set-status deferred --execute --db porting.db
```

**Step 6: Verify remaining count decreased**

```bash
dotnet run --project tools/NatsNet.PortTracker -- feature list --status unknown --db porting.db
```

Confirm the total decreased by ~50 from the previous batch.

**Step 7: Report batch summary**

Print: `Batch N: X verified, Y stub, Z n_a, W deferred (Total remaining: NNNN)`

---

### Task 69: Final verification and report

**Files:** None — verification only.

**Step 1: Confirm zero unknown features remain**

```bash
dotnet run --project tools/NatsNet.PortTracker -- feature list --status unknown --db porting.db
```

Expected: `Total: 0 features`

**Step 2: Generate the full status breakdown**

```bash
dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status verified --db porting.db
dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status stub --db porting.db
dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status n_a --db porting.db
dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status deferred --db porting.db
```

Note the count for each status.

**Step 3: Generate updated porting report**

```bash
./reports/generate-report.sh
```

**Step 4: Commit the updated report**

```bash
git add reports/
git commit -m "chore: update porting report after feature status audit"
```

**Step 5: Print final summary**

```
Feature Status Audit Complete
=============================
Total features audited: 3394
  verified:  NNNN
  stub:      NNNN
  n_a:       NNNN
  deferred:  NNNN
```