natsnet/docs/plans/2026-02-27-batch-17-client-core-second-half-design.md

# Batch 17 (Client Core second half) Design

**Date:** 2026-02-27  
**Scope:** Design only for Batch 17 (`server/client.go` second-half mappings): 60 features and 9 tracked tests.

## Context Snapshot

Batch metadata from PortTracker:

- Batch ID: `17`
- Name: `Client Core (second half)`
- Dependency: batch `16`
- Go file: `server/client.go`
- Features: `60` (all currently `deferred`)
- Tests: `9` (all currently `deferred`)

Tracker status snapshot (`report summary`):

- Features: `1271 verified`, `2377 deferred`, `24 n_a`, `1 stub`
- Unit tests: `430 verified`, `2640 deferred`, `187 n_a`
- Overall progress: `1924 / 6942 (27.7%)`

## Problem Statement

Batch 17 is the heaviest `client.go` section: subscription/unsubscribe paths, delivery fanout, inbound message processing, header mutation helpers, service import plumbing, ping/stale timers, account-reload handling, reconnect/TLS handshakes, and rate-limited logging.

The main execution risk is false progress through placeholder methods/tests because:

1. `ClientConnection.cs` still contains explicit second-half stubs/comments.
2. Batch 17 tests include JetStream/FileStore/MemStore/Server tests with many non-Batch-17 deferred dependencies.
3. Existing backlog tests include shallow placeholder patterns that can pass without validating behavior.

## Working Set Breakdown

Feature groups (max ~20 each):

- **Group A (20):** `477-496`  
  Subscription shadowing, unsubscribe flow, message header composition, `deliverMsg`, permission pruning, publish allow checks, reply classifiers.
- **Group B (20):** `497-515,520`  
  Inbound message pipeline, reply/service import handling, header get/set/remove helpers, `processServiceImport`, route-target accumulation, `processMsgResults`, ping timer processing.
- **Group C (20):** `521,522,534,535,537,540,541,542,543,544,545,546,547,548,553,565,566,567,568,569`  
  Ping interval adjustments, stale watcher, reload/reconnect/account cache helpers, `ClientInfo.serviceAccount`, client info enrichment, TLS handshake trio, allowed connection type conversion, rate-limit logging, first ping timer.

Tracked tests:

- File store scheduling/delete-marker cluster: `528,545,552,553,568,598`
- Memory store scheduling/delete-marker cluster: `2053,2057`
- Server rate-limit logging: `2901`

## Approaches

### Approach A: Monolithic `ClientConnection.cs` port wave

Implement all 60 features in the existing file, then patch tests.

- Pros: fewer files and simpler search path.
- Cons: high merge risk, hard reviewability, harder to isolate regressions.

### Approach B (Recommended): Three vertical feature groups with partial-class split and hard gates

Split second-half methods into focused `ClientConnection` partial files and execute three 20-feature groups with explicit build/test/stub gates between groups.

- Pros: reviewable increments, clearer ownership per concern, strong regression isolation.
- Cons: slightly more up-front file organization.

### Approach C: Wrapper-heavy defer-first strategy

Add shallow wrappers for signatures, defer behavior-heavy methods and most tests.

- Pros: fastest status movement.
- Cons: poor parity confidence, audit churn, high risk of anti-stub violations.

## Recommended Design

### 1. Architecture

- Keep `ClientConnection` as the primary host, but split second-half methods into dedicated partial files:
  - `ClientConnection.SubscriptionsAndDelivery.cs` (Group A)
  - `ClientConnection.InboundAndHeaders.cs` (Group B)
  - `ClientConnection.LifecycleAndTls.cs` (Group C)
- Keep `ClientInfo.serviceAccount` logic in `ClientTypes.cs` (or a focused companion file if needed).
- Preserve existing first-half behavior in `ClientConnection.cs`; do not refactor unrelated code.

### 2. Data/Control Flow

- Inbound path: `processInboundMsg` -> subject mapping/service-import path -> `processMsgResults`.
- Delivery path: `deliverMsg` + header generation + permission/reply tracking.
- Timer/lifecycle path: ping interval decisions, stale detection, reconnect, and handshake transitions.
- Logging path: rate-limited wrappers funneling through existing server/client logging facilities.

### 3. Error Handling and Deferral

- Port behavior from Go line ranges, including close reasons and permission-deny behavior.
- If a feature/test requires missing infra (outside Batch 17 dependencies), keep it `deferred` with explicit reason and evidence.
- Never use placeholder success paths to force status transitions.

### 4. Test Strategy

- Add/expand focused client-core tests first (to make feature verification real).
- Attempt the 9 tracked tests only after dependency precheck and feature readiness.
- For blocked tests, keep `deferred` with concrete blocker notes rather than adding shallow assertions.

### 5. Verification Contract

- Per-feature read/implement/build/test loop.
- Group-level stub scan, build gate, and related test gate before status promotion.
- Chunked status updates (`<=15` IDs/update) with captured evidence.

## Risks and Mitigations

1. **Large method complexity (`deliverMsg`, `processMsgResults`)**  
   Mitigation: isolate in Group A/B, add targeted tests before and after each port.
2. **Cross-module test blockers (FileStore/MemStore/Server dependencies)**  
   Mitigation: dependency precheck before each test; defer with explicit reason when blocked.
3. **Stub regression under schedule pressure**  
   Mitigation: mandatory anti-stub scans and hard status gates.

## Success Criteria

1. All 60 Batch 17 features are either behavior-verified or explicitly deferred with reason.
2. All 9 Batch 17 tests are either genuinely verified or explicitly deferred with reason.
3. No forbidden stub patterns remain in touched feature/test files.
4. Status updates are evidence-backed, chunked, and auditable.

## Non-Goals

1. No implementation in this design document.
2. No unrelated refactors outside Batch 17 scope.
3. No synthetic "pass" tests or placeholder feature logic to satisfy tracker states.