# Deferred Features Implementation Design

**Date**: 2026-03-01
**Status**: Draft
**Scope**: 363 deferred features + 1 stub across 6 batches

## Context

After completing batches 16-41, 363 features remain deferred (plus 1 stub). These were deferred because they require server runtime infrastructure — event dispatch loops, HTTP monitoring endpoints, MQTT session management, and account resolver dispatch.

Current state: 82.0% complete (5694/6942 items). This work targets bringing features to ~92% (all 363 + 1 stub → verified).

884 deferred tests (mostly integration/cluster tests) are out of scope — they remain deferred for a future integration testing phase.

## Decisions

- **Implementation depth**: Full method bodies ported from Go to idiomatic C#. Methods will be functionally correct and will work once server runtime boots, but won't be exercised by tests yet.
- **Tests**: No new unit tests for these features. All 884 deferred tests remain deferred.
- **Execution**: Parallel Claude Code Sonnet agents with `isolation: "worktree"`, 2-3 concurrent.
- **PortTracker updates**: Run audit after each batch merge to promote features to verified.

## Batch Structure

### Batch 42: Foundation Helpers (54 features)

MsgTrace full implementation (28), GatewayInterestMode.String (1), monitor standalone helpers (25).

**Target files**:
- `MessageTrace/MsgTrace.cs` (new or extend existing `MsgTraceTypes.cs`)
- `Monitor/MonitorHelpers.cs` (new)
- `Gateway/GatewayTypes.cs` (extend)

**Feature IDs**:
- MsgTrace: 2406-2413, 2420-2439
- Gateway: 1265
- Monitor helpers: 2166-2167, 2170-2171, 2173-2177, 2181-2182, 2188-2189, 2194, 2196, 2200, 2202-2204, 2206-2207, 2213-2214, 2216, 2219

**Dependencies**: None (foundation layer)

### Batch 43: Accounts Resolvers & Service Latency (37 features)

Account resolver implementations (URL, Dir, CacheDir), service export timers, latency tracking, JWT/claims validation, tracing headers.

**Target files**:
- `Accounts/AccountResolver.cs` (extend with URL, Dir, CacheDir implementations)
- `Accounts/Account.ServiceExports.cs` (new or extend)
- `Accounts/AccountTypes.cs` (extend)
- `NatsServer.Accounts.cs` (extend)

**Feature IDs**: 150, 183, 208-209, 215, 250-253, 258-261, 306-307, 310, 316, 318-320, 326-328, 330-331, 334-339, 341, 343, 345-347, 349

**Dependencies**: None (foundation layer)

### Batch 44: Events Core & Dispatch (46 features)

Event system foundation: helpers, ServerInfo capabilities, ClientInfo factory methods, internal send/receive loops, system subscription infrastructure.

**Target files**:
- `Events/EventHelpers.cs` (new)
- `Events/EventTypes.cs` (extend ServerInfo, ClientInfo)
- `NatsServer.Events.cs` (new partial — core dispatch)

**Feature IDs**:
- Helpers: 863, 882, 890-891, 912, 935, 939, 945-947
- ServerInfo: 854-859
- ClientInfo: 860-862
- pubMsg: 864
- client: 875
- Account: 920
- Server dispatch: 865-866, 868, 871-874, 876-878, 892-893, 909, 927-934, 937-938, 948

**Dependencies**: Batch 42 (MsgTrace types used by event sending)

### Batch 45: Events Server Methods (42 features)

All remaining Server.* event methods: stats broadcasting, remote server tracking, account connection events, OCSP events, reload config notifications.

**Target files**:
- `NatsServer.Events.cs` (extend)
- `NatsServer.EventsRemote.cs` (new partial — remote server handling)

**Feature IDs**: 879-881, 883-889, 894-895, 897-905, 907-908, 910-911, 913-914, 917-919, 921, 923, 925-926, 936, 940-944, 949-950

**Dependencies**: Batch 44 (uses core dispatch infrastructure)

### Batch 46: Monitor Endpoints (45 features)

HTTP monitoring endpoint implementations: Varz, Connz, Routez, Subsz, Gatewayz, Leafz, Accountz, Jsz, Healthz, Raftz, plus handler wrappers and type methods.

**Target files**:
- `NatsServer.Monitor.cs` (new partial — all endpoint methods)
- `Monitor/MonitorTypes.cs` (extend with fill/String/Marshal methods)

**Feature IDs**: 2168-2169, 2172, 2178-2180, 2183-2187, 2190-2193, 2195, 2197-2199, 2201, 2205, 2208-2212, 2215, 2217-2218, 2220-2235

**Dependencies**: Batch 42 (monitor helpers)

### Batch 47: MQTT Full Runtime (139 features)

Complete MQTT implementation: mqttJSA (JetStream API bridge, 22), mqttSession (session lifecycle, 15), mqttAccountSessionManager (retained messages, session persistence, 26), Server.mqtt* (connection handling, 17), client.mqtt* (protocol parsing, 24), standalone helpers (35).

**Target files**:
- `Mqtt/MqttJsa.cs` (new — JetStream API bridge)
- `Mqtt/MqttSession.cs` (new — session state machine)
- `Mqtt/MqttAccountSessionManager.cs` (new — account-level session manager)
- `Mqtt/MqttHandler.cs` (extend — server-side handlers)
- `Mqtt/MqttReader.cs` (extend — protocol parsing)
- `Mqtt/MqttWriter.cs` (extend — protocol writing)
- `NatsServer.Mqtt.cs` (new partial — server integration)
- `ClientConnection.Mqtt.cs` (new partial — client-side methods)

**Feature IDs**: 2252-2255, 2257-2268, 2269-2290, 2291-2327, 2328-2404 (all 139 mqtt.go deferred features)

**Dependencies**: Batches 44+45 (MQTT uses event infrastructure for advisories)

### Stub Feature (added to Batch 42)

- Feature 2962: `scheduler.go:getScheduledMessages` — currently stub, implement fully

## Execution Plan

### Wave 1 (parallel)
- **Batch 42** (Foundation Helpers, 54 features)
- **Batch 43** (Accounts, 37 features)

### Wave 2 (parallel, after Wave 1)
- **Batch 44** (Events Core, 46 features)
- **Batch 46** (Monitor Endpoints, 45 features)

### Wave 3 (after Batch 44)
- **Batch 45** (Events Server, 42 features)

### Wave 4 (after Batch 45)
- **Batch 47** (MQTT Runtime, 139 features)

## Post-Execution

After all batches merge:
1. Run `dotnet build dotnet/` to confirm compilation
2. Run `dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/` to confirm no regressions
3. Reset deferred→unknown in porting.db, re-run audit
4. Generate final report

## Expected Outcome

- Features: 3263 + 363 + 1 = 3627 verified (vs 3673 total = 98.7%)
- Remaining: 22 complete, 24 n/a = stable
- Tests: 2066 verified + audit promotions (deferred integration tests remain)