natsnet/docs/plans/2026-02-27-batch-35-js-cluster-remaining-design.md

Batch 35 JS Cluster Remaining Design

Date: 2026-02-27
Batch: 35 (JS Cluster Remaining)
Scope: 57 features + 49 unit tests
Dependency: batch 32 (JS Cluster Meta)
Go source: golang/nats-server/server/jetstream_cluster.go

Problem

Batch 35 covers the remaining JetStream cluster behavior in server/jetstream_cluster.go (roughly lines 8766-10866): delete-range and assignment encoding/decoding, stream snapshot/catchup processing, cluster info assembly, catchup throttling counters, and sync subject helpers. It also includes 49 tests, mostly RaftNodeTests, that validate catchup/truncation and snapshot correctness.

The plan must prevent false progress: no placeholder feature ports and no fake-pass tests.

Context Findings

Required command outputs

• /usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch show 35 --db porting.db
  • Status: pending
  • Features: 57 (all deferred)
  • Tests: 49 (all deferred)
  • Depends on: 32
  • Go file: server/jetstream_cluster.go
• /usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch list --db porting.db
  • Confirms chain around this area: 32 -> 33/34/35.
• /usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db
  • Overall progress: 1924/6942 (27.7%)

Environment note: dotnet was not on PATH in this shell; use /usr/local/share/dotnet/dotnet.

Feature ownership distribution (from porting.db)

• NatsStream: 27
• JetStreamCluster: 19
• NatsServer: 8
• JetStreamEngine: 3

Test distribution (from porting.db)

• RaftNodeTests: 42
• JetStreamClusterTests1: 6
• JetStreamBatchingTests: 1

Constraints and Success Criteria

• Planning only; no implementation execution in this session.
• Reuse Batch 0 rigor, but for features + tests.
• Feature tasks must be grouped in chunks of max ~20 features.
• Status updates must use batch-update chunks of at most 15 IDs.
• Blocked work must be marked deferred with explicit reason, never stubbed.

Success means all 57 feature IDs and 49 test IDs are either:

• promoted with verification evidence (complete/verified), or
• kept deferred with specific blocker notes.

Approaches

Approach A: Monolithic pass (all features, then all tests)

• Pros: simple sequencing.
• Cons: high risk, poor auditability, hard to isolate regressions.

Approach B (Recommended): Three feature groups plus four test waves with hard gates

• Pros: bounded scope, clearer rollback points, aligns with max-20 feature grouping and max-15 status updates.
• Cons: more command overhead.

Approach C: Test-first for all 49 tests before feature completion

• Pros: immediate behavior pressure.
• Cons: high churn because most tests depend on unported catchup/snapshot internals.

Decision: Approach B.

Proposed Design

1. Code Organization

Use behavior-focused files while keeping existing class ownership:

• dotnet/src/ZB.MOM.NatsNet.Server/JetStream/JetStreamClusterTypes.cs
  • assignment/sync subject encode/decode helpers and cluster utility functions.
• dotnet/src/ZB.MOM.NatsNet.Server/JetStream/NatsStream.cs
  • snapshot and catchup state transitions plus inbound cluster message processing.
• dotnet/src/ZB.MOM.NatsNet.Server/JetStream/JetStreamTypes.cs
  • offline/online cluster info and alternate-stream assembly.
• dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.cs and/or new partial NatsServer.JetStreamClusterRemaining.cs
  • clustered consumer request path and gcb accounting helpers.

2. Feature Grouping (max ~20)

• Group A (20 IDs): 1694-1713
  Delete-range, consumer assignment, stream/batch encode-decode, snapshot support/state capture, clustered inbound message entry point.
• Group B (20 IDs): 1714-1733
  Delete trace, sync request calculation, snapshot delete handling, catchup peer lifecycle, snapshot/catchup processing, stream sync handler, cluster info base methods.
• Group C (17 IDs): 1734-1750
  Cluster info checks, stream alternates/info request handling, gcb accounting/kick channel, run-catchup loop, sync subject helper family.

3. Test Wave Grouping

• Wave T1 (7 IDs): 730,846,847,848,890,891,893 (JetStreamBatchingTests + JetStreamClusterTests1)
• Wave T2 (14 IDs): 2640,2641,2643,2644,2645,2646,2647,2648,2649,2653,2655,2656,2658,2659
• Wave T3 (14 IDs): 2660,2661,2662,2665,2666,2668,2669,2673,2676,2677,2678,2679,2680,2681
• Wave T4 (14 IDs): 2682,2683,2684,2685,2686,2688,2691,2696,2697,2703,2715,2716,2717,2719

4. Verification Strategy (Design-Level)

• Every feature follows a per-feature loop with focused test evidence.
• Every test follows method-level then class-level verification.
• Stub detection runs after each loop and before status promotions.
• Build and targeted/full test gates are mandatory before checkpoint status updates.
• Checkpoints occur between every task boundary.

5. Deferral Strategy

If infrastructure or dependency behavior blocks a feature/test:

1. Stop work on that ID.
2. Do not add placeholder implementation/assertions.
3. Mark deferred with explicit reason via --override.
4. Continue with next unblocked item.

Risks and Mitigations

• Dependency readiness risk (Batch 32): enforce preflight before batch start 35.
• Raft-heavy test concentration: split RaftNodeTests into three equal waves and checkpoint each wave.
• Stub regression under volume: hard anti-stub scans and strict status chunking (<=15).
• Class ownership drift: keep methods in mapped classes only (JetStreamCluster, NatsStream, JetStreamEngine, NatsServer).

Non-Goals

• Executing the implementation in this session.
• Expanding scope beyond Batch 35 mappings.
• Changing batch dependencies/order in PortTracker.