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.