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:

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:

# 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

# 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.

# 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.

# 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:

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:

# 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:

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:

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

# 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:

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 -- the mapping phase this verifies
• Phase 6: Porting -- uses the verified mappings for implementation