natsnet/docs/plans/phases/phase-5-mapping-verification.md

# Phase 5: Mapping Verification

Verify that every Go item in the porting database is either mapped to a .NET target or justified as N/A. This phase is a quality gate between design (Phase 4) and implementation (Phase 6).

## Objective

Confirm zero unmapped items, validate all N/A justifications, enforce naming conventions, and detect collisions. The porting database must be a complete, consistent blueprint before any code is written.

## Prerequisites

- Phase 4 complete: all items have .NET mappings or N/A status
- Verify with: `dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db`

## Steps

### Step 1: Confirm zero unmapped items

Run the summary report and verify that no items remain in `not_started` status without a .NET mapping:

```bash
dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db
```

The output shows counts per status. All items should be in one of these categories:

- `not_started` with .NET mapping fields populated (ready for Phase 6)
- `n_a` with a reason in the notes field

If any items lack both a mapping and N/A status, go back to Phase 4 and address them.

### Step 2: Review N/A items

Every N/A item must have a justification. Review them by type:

```bash
# Review N/A modules
dotnet run --project tools/NatsNet.PortTracker -- module list --status n_a --db porting.db

# Review N/A features
dotnet run --project tools/NatsNet.PortTracker -- feature list --status n_a --db porting.db

# Review N/A tests
dotnet run --project tools/NatsNet.PortTracker -- test list --status n_a --db porting.db
```

For each N/A item, verify:

1. The reason is documented (check with `module show <id>`, `feature show <id>`, or `test show <id>`)
2. The reason is valid (the item genuinely has no .NET equivalent or is replaced by a .NET facility)
3. No dependent items rely on this N/A item being ported

```bash
# Check if anything depends on an N/A item
dotnet run --project tools/NatsNet.PortTracker -- dependency show module <id> --db porting.db
dotnet run --project tools/NatsNet.PortTracker -- dependency show feature <id> --db porting.db
```

If a non-N/A item depends on an N/A item, either the dependency needs to be resolved differently or the N/A classification is wrong.

### Step 3: Verify naming conventions

Walk through the mappings and check for naming compliance:

**PascalCase check**: All `dotnet_class` and `dotnet_method` values must use PascalCase. No `snake_case`, no `camelCase`.

```bash
# List all mapped modules and spot-check names
dotnet run --project tools/NatsNet.PortTracker -- module list --db porting.db

# List all mapped features for a module and check class/method names
dotnet run --project tools/NatsNet.PortTracker -- feature list --module <id> --db porting.db
```

**Namespace hierarchy check**: Namespaces must follow `NATS.Server.[Module]` pattern:

| Valid | Invalid |
|-------|---------|
| `NATS.Server.Protocol` | `Protocol` (missing root) |
| `NATS.Server.JetStream` | `NATS.Server.jetstream` (wrong case) |
| `NATS.Server.Subscriptions` | `NATSServer.Subscriptions` (wrong root) |

**Test naming check**: Test classes must end in `Tests`. Test methods must follow `[Method]_[Scenario]_[Expected]` pattern:

| Valid | Invalid |
|-------|---------|
| `NatsParserTests` | `ParserTest` (wrong suffix) |
| `TryParse_ValidInput_ReturnsTrue` | `TestParserValid` (Go-style naming) |
| `Match_WildcardSubject_ReturnsSubscribers` | `test_match` (snake_case) |

### Step 4: Check for collisions

No two features should map to the same class + method combination. This would cause compile errors or overwrite conflicts.

```bash
# Export the full mapping report for review
dotnet run --project tools/NatsNet.PortTracker -- report export --format md --output porting-mapping-report.md --db porting.db
```

Open `porting-mapping-report.md` and search for duplicate class + method pairs. If the database is large, run a targeted SQL query:

```bash
sqlite3 porting.db "
  SELECT dotnet_class, dotnet_method, COUNT(*) as cnt
  FROM features
  WHERE dotnet_class IS NOT NULL AND dotnet_method IS NOT NULL
  GROUP BY dotnet_class, dotnet_method
  HAVING cnt > 1;
"
```

If collisions are found, rename one of the conflicting methods. Common resolution: add a more specific suffix (`ParseHeaders` vs `ParseBody` instead of two `Parse` methods).

### Step 5: Validate cross-references

Verify that test mappings reference the correct test project:

```bash
# All tests should target NATS.Server.Tests or NATS.Server.IntegrationTests
dotnet run --project tools/NatsNet.PortTracker -- test list --db porting.db
```

Check that:
- Unit tests point to `NATS.Server.Tests`
- Integration tests (if any) point to `NATS.Server.IntegrationTests`
- No tests accidentally point to `NATS.Server` (the library project)

### Step 6: Run phase check

Run the built-in phase verification:

```bash
dotnet run --project tools/NatsNet.PortTracker -- phase check 5 --db porting.db
```

This runs automated checks and reports any remaining issues. All checks must pass.

### Step 7: Export final mapping report

Generate the definitive mapping report that serves as the implementation reference for Phase 6:

```bash
dotnet run --project tools/NatsNet.PortTracker -- report export \
  --format md \
  --output porting-mapping-report.md \
  --db porting.db
```

Review the exported report for completeness. This document becomes the source of truth for the porting work.

## Troubleshooting

### Unmapped items found

```bash
# Find features with no .NET mapping and not N/A
dotnet run --project tools/NatsNet.PortTracker -- feature list --status not_started --db porting.db
```

For each unmapped item, either map it (Phase 4 Step 2) or set it to N/A with a reason.

### N/A item has dependents

If a non-N/A feature depends on an N/A feature:

1. Determine if the dependency is real or an artifact of the Go call graph
2. If real, the N/A classification is likely wrong -- map the item instead
3. If the dependency is Go-specific, remove or reclassify it

### Naming collision detected

Rename one of the colliding methods to be more specific:

```bash
dotnet run --project tools/NatsNet.PortTracker -- feature map <id> \
  --method "ParseHeadersFromBuffer" \
  --db porting.db
```

## Completion Criteria

- Zero items in `not_started` status without a .NET mapping
- All N/A items have a documented, valid reason
- All `dotnet_class` and `dotnet_method` values follow PascalCase
- All namespaces follow `NATS.Server.[Module]` hierarchy
- No two features map to the same class + method combination
- All tests target the correct test project
- `phase check 5` passes with no errors
- Mapping report exported and reviewed

## Related Documentation

- [Phase 4: .NET Solution Design](phase-4-dotnet-design.md) -- the mapping phase this verifies
- [Phase 6: Porting](phase-6-porting.md) -- uses the verified mappings for implementation