natsnet/docs/plans/2026-02-26-phase7-design.md

# Phase 7: Porting Verification — Design

**Date:** 2026-02-26
**Scope:** Verify all ported code through targeted testing; mark server-integration tests as `deferred`

---

## Context

After Phase 6 (23 porting sessions + 93 stub completions), the DB state entering Phase 7:

| Item | Count |
|------|-------|
| Features complete | 3,596 / 3,673 (77 n_a) |
| Unit tests complete | 319 |
| Unit tests stub | 224 |
| Unit tests not_started | 2,533 |
| Unit tests n_a | 181 |
| Unit tests total | 3,257 |

635 unit tests currently pass. 166 `NotImplementedException` stubs remain in the server — the .NET server is not yet runnable end-to-end.

---

## Key Design Decision: Two Test Layers

Go test files (`jetstream_test.go`, `monitor_test.go`, etc.) all use `RunBasicJetStreamServer()` / `RunServer()` — they start a real NATS server over TCP, then connect via NATS client. These are server-integration tests regardless of whether they target a single node or a cluster.

| Layer | Tests | Treatment |
|-------|-------|-----------|
| **Unit** | Pure component logic (no server startup) | Port & verify in Phase 7 |
| **Server-integration** | Require running NatsServer + NATS client | Status `deferred` |

---

## Schema Extension

Add `deferred` to the `unit_tests.status` CHECK constraint:

```sql
-- Migration: add 'deferred' to unit_tests status enum
-- Recreate table with updated constraint or use SQLite trigger workaround
```

`deferred` = test blocked on running server or cluster infrastructure. Distinct from `n_a` (not applicable to this port).

---

## Test Classification

### Unit Tests to Port (~631 new tests)

| Go source file | Not-started / Stub | Component |
|---|---|---|
| `opts_test.go` | 77 stubs + remaining | Config parsing / binding |
| `jwt_test.go` | 88 stubs | JWT decode / validate |
| `auth_test.go` | 6 stubs | Auth handler logic |
| `auth_callout_test.go` | 31 stubs | Auth callout types / helpers |
| `signal_test.go` | 16 stubs | Signal handler registration |
| `log_test.go` | 3 stubs | Logger behaviour |
| `config_check_test.go` | 3 stubs | Config validation |
| `memstore_test.go` | 41 not_started | Memory store logic |
| `store_test.go` | 17 not_started | Store interface contract |
| `filestore_test.go` | 249 not_started | File store read/write/purge |
| `jetstream_errors_test.go` | 4 not_started | Error type checks |
| `jetstream_versioning_test.go` | 18 not_started | Version compatibility |
| `jetstream_batching_test.go` | 29 not_started | Batching logic |
| `dirstore_test.go` | 12 not_started | JWT directory store |
| `accounts_test.go` | 31 not_started | Account logic (unit subset) |
| `thw` module | 6 not_started | Time hash wheel |

### Server-Integration Tests → `deferred` (~1,799 tests)

| Go source file | Count | Deferred reason |
|---|---|---|
| `jetstream_test.go` | 320 | Needs running server |
| `jetstream_consumer_test.go` | 161 | Needs running server |
| `monitor_test.go` | 103 | HTTP monitoring endpoints |
| `reload_test.go` | 73 | Live config reload |
| `routes_test.go` | 70 | Multi-server routing |
| `events_test.go` | 52 | Server event bus |
| `server_test.go` | 20 | Server lifecycle |
| `jetstream_cluster_*` (×4) | 456 | Multi-node cluster |
| `mqtt_test.go` + extras | ~162 | MQTT server |
| `websocket_test.go` | 109 | WebSocket server |
| `raft_test.go` | 104 | Raft consensus |
| `leafnode_test.go` + proxy | 120 | Leaf node infrastructure |
| `gateway_test.go` | 88 | Gateway infrastructure |
| `jetstream_super_cluster_test.go` | 47 | Super-cluster |
| `norace_*` tests | ~141 | Race-detector / timing |
| Benchmark tests | ~20 | Performance only |
| Other cluster/misc | ~53 | Cluster infrastructure |

---

## Session Structure (10 sessions)

| Session | Scope | New tests | Source files |
|---------|-------|-----------|---|
| **P7-01** | Schema migration + small module verification | 0 new (114 existing) | ats, avl, certidp, gsl, pse, stree, thw, tpm |
| **P7-02** | Opts & config stubs + remaining opts tests | ~95 | `opts_test.go` |
| **P7-03** | JWT stubs | 88 | `jwt_test.go` |
| **P7-04** | Auth stubs + auth callout stubs | 37 | `auth_test.go`, `auth_callout_test.go`, `config_check_test.go` |
| **P7-05** | Signal + log stubs | 19 | `signal_test.go`, `log_test.go` |
| **P7-06** | Store unit tests — memory + interface | ~58 | `memstore_test.go`, `store_test.go` |
| **P7-07** | File store unit tests (first half) | ~125 | `filestore_test.go` lines 1–~4,000 |
| **P7-08** | File store unit tests (second half) | ~124 | `filestore_test.go` remainder |
| **P7-09** | JetStream unit tests — errors, versioning, batching, dirstore, accounts | ~94 | `jetstream_errors_test.go`, `jetstream_versioning_test.go`, `jetstream_batching_test.go`, `dirstore_test.go`, `accounts_test.go` |
| **P7-10** | Mark deferred, integration tests, DB final update, Phase 7 close | — | DB sweep + Gitea milestones 7 & 8 |

**Total new tests written: ~640**

---

## Verification Flow (per session)

1. Write / fill tests → build → run → confirm green
2. Mark tests `complete` in DB (new tests) then `verified`
3. Mark small modules `verified` in DB (P7-01); server module at P7-10
4. `./reports/generate-report.sh` → commit

---

## Integration Tests (P7-10)

Replace the placeholder `UnitTest1.cs` with `NatsServerBehaviorTests.cs`. Tests run against the **Go NATS server** (not the .NET server) to establish a behavioral baseline:

- Basic pub/sub
- Wildcard matching (`foo.*`, `foo.>`)
- Queue groups
- Connect/disconnect lifecycle
- Protocol error handling

---

## Completion Definition

Phase 7 is complete when:
- All non-`n_a`, non-`deferred` tests are `verified`
- `dotnet run --project tools/NatsNet.PortTracker -- phase check 7 --db porting.db` passes
- Gitea issues #45–#52 closed
- Gitea milestones 7 and 8 closed

The ~1,799 `deferred` tests remain for a future phase once the .NET server is end-to-end runnable.