natsnet/docs/plans/phases/phase6sessions/readme.md

Phase 6 Sessions: Server Module Breakdown

The server module (module 8) contains 3,394 features, 3,137 unit tests, and ~103K Go LOC across 64 source files. It has been split into 23 sessions targeting ~5K Go LOC each, ordered by dependency (bottom-up).

Session Map

Session	Name	Go LOC	Features	Tests	Go Files
01	Foundation Types	626	46	17	const, errors, errors_gen, proto, ring, rate_counter, sdm, nkey
02	Utilities & Queues	1,325	68	57	util, ipqueue, sendq, scheduler, subject_transform
03	Configuration & Options	5,400	86	89	opts
04	Logging, Signals & Services	534	34	27	log, signal*, service*
05	Subscription Index	1,416	81	96	sublist
06	Auth & JWT	2,196	43	131	auth, auth_callout, jwt, ciphersuites
07	Protocol Parser	1,165	5	17	parser
08	Client Connection	5,953	195	113	client, client_proxyproto
09	Server Core — Init & Config	~1,950	~76	~20	server.go (first half)
10	Server Core — Runtime & Lifecycle	~1,881	~98	~27	server.go (second half)
11	Accounts & Directory Store	4,493	234	84	accounts, dirstore
12	Events, Monitoring & Tracing	6,319	218	188	events, monitor, monitor_sort_opts, msgtrace
13	Configuration Reload	2,085	89	73	reload
14	Routes	2,988	57	70	route
15	Leaf Nodes	3,091	71	120	leafnode
16	Gateways	2,816	91	88	gateway
17	Store Interfaces & Memory Store	2,879	135	58	store, memstore, disk_avail*
18	File Store	11,421	312	249	filestore
19	JetStream Core	9,504	374	406	jetstream, jetstream_api, jetstream_errors*, jetstream_events, jetstream_versioning, jetstream_batching
20	JetStream Cluster & Raft	14,176	429	617	raft, jetstream_cluster
21	Streams & Consumers	12,700	402	315	stream, consumer
22	MQTT	4,758	153	162	mqtt
23	WebSocket & OCSP	2,962	97	113	websocket, ocsp, ocsp_peer, ocsp_responsecache
	Totals	~103K	3,394	3,137

Dependency Graph

S01 Foundation
 ├── S02 Utilities
 ├── S03 Options
 ├── S04 Logging
 ├── S05 Sublist ← S02
 ├── S06 Auth ← S03
 └── S07 Parser

S08 Client ← S02, S03, S05, S07

S09 Server Init ← S03, S04, S05, S06
S10 Server Runtime ← S08, S09

S11 Accounts ← S02, S03, S05, S06
S12 Events & Monitor ← S08, S09, S11
S13 Reload ← S03, S09

S14 Routes ← S07, S08, S09
S15 Leafnodes ← S07, S08, S09, S14
S16 Gateways ← S07, S08, S09, S11, S14

S17 Store Interfaces ← S01, S02
S18 FileStore ← S17
S19 JetStream Core ← S08, S09, S11, S17
S20 JetStream Cluster ← S14, S17, S19
S21 Streams & Consumers ← S08, S09, S11, S17, S19

S22 MQTT ← S08, S09, S11, S17, S19
S23 WebSocket & OCSP ← S08, S09

Multi-Sitting Sessions

Sessions 18, 19, 20, and 21 exceed the ~5K target and include sub-batching guidance in their individual files. Plan for 2-3 sittings each.

Session	Go LOC	Recommended Sittings
S18 File Store	11,421	2-3
S19 JetStream Core	9,504	2-3
S20 JetStream Cluster & Raft	14,176	3-4
S21 Streams & Consumers	12,700	2-3

Execution Order

Sessions should be executed roughly in order (S01 → S23), but parallel tracks are possible:

Track A (Core): S01 → S02 → S03 → S04 → S05 → S07 → S08 → S09 → S10

Track B (Auth/Accounts): S06 → S11 (after S03, S05)

Track C (Networking): S14 → S15 → S16 (after S08, S09)

Track D (Storage): S17 → S18 (after S01, S02)

Track E (JetStream): S19 → S20 → S21 (after S09, S11, S17)

Track F (Protocols): S22 → S23 (after S08, S09, S19)

Cross-cutting: S12, S13 (after S09, S11)

How to Use

Starting point

Begin with Session 01 (Foundation Types). It has no dependencies and everything else builds on it.

Session loop

Repeat until all 23 sessions are complete:

1. Pick the next session. Work through sessions in numerical order (S01 → S23). The numbering follows the dependency graph, so each session's prerequisites are already done by the time you reach it. If you want to parallelise, check the dependency graph above — any session whose dependencies are all complete is eligible.

2. Open a new Claude Code session. Reference the session file:

   Port session N per docs/plans/phases/phase6sessions/session-NN.md
   

3. Port features. For each feature in the session:

   • Mark as stub in porting.db
   • Implement the .NET code referencing the Go source
   • Mark as complete in porting.db

4. Port tests. For each test listed in the session file:

   • Implement the xUnit test
   • Run it: dotnet test --filter "FullyQualifiedName~ClassName"
   • Mark as complete in porting.db

5. Verify the build. Run dotnet build and dotnet test to confirm nothing is broken.

6. Commit. Commit all changes with a message like feat: port session NN — <session name>.

7. Check progress.

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

Multi-sitting sessions

Sessions 18, 19, 20, and 21 are too large for a single sitting. Each session file contains sub-batching guidance (e.g., 18a, 18b, 18c). Commit after each sub-batch rather than waiting for the entire session.

Completion

All 23 sessions are done when:

• Every feature in module 8 is complete or n/a
• Every unit test in module 8 is complete or n/a
• dotnet build succeeds
• dotnet test passes