# Batch 2 (Parser, Sublist, MemStore remainders) Design

**Date:** 2026-02-27  
**Scope:** Design only for implementing and verifying Batch 2 feature ports (8 features, 0 tracked tests).

## Context Snapshot

Batch metadata (from `porting.db`):

- Batch ID: `2`
- Name: `Parser, Sublist, MemStore remainders`
- Features: `8`
- Tests: `0`
- Dependencies: `Batch 1`
- Go files: `server/memstore.go`, `server/parser.go`, `server/sublist.go`

Feature IDs in this batch:

- `2068` `newMemStore` -> `JetStreamMemStore.NewMemStore`
- `2086` `memStore.allLastSeqsLocked` -> `JetStreamMemStore.AllLastSeqsLocked`
- `2588` `client.parse` -> `ClientConnection.Parse`
- `2590` `client.overMaxControlLineLimit` -> `ClientConnection.OverMaxControlLineLimit`
- `2591` `client.clonePubArg` -> `ClientConnection.ClonePubArg`
- `3446` `level.pruneNode` -> `Level.PruneNode`
- `3447` `node.isEmpty` -> `Node.IsEmpty`
- `3448` `level.numNodes` -> `Level.NumNodes`

## Current Code Findings

1. Parser behavior exists in `dotnet/src/ZB.MOM.NatsNet.Server/Protocol/ProtocolParser.cs`:
   - `Parse` at line 36
   - `OverMaxControlLineLimit` at line 781
   - `ClonePubArg` at line 1096
2. `JetStreamMemStore` has constructor parity for `newMemStore` and `AllLastSeqs` behavior in `dotnet/src/ZB.MOM.NatsNet.Server/JetStream/MemStore.cs` (constructor line 81, `AllLastSeqs` line 1131).
3. Sublist helper behavior exists in both data-structure implementations:
   - `SubscriptionIndex.cs` nested node/level helpers (`IsEmpty`, `NumNodes`, `PruneNode`)
   - `GenericSublist.cs` trie helper equivalents (`IsEmpty`, `NumNodes`, `PruneNode`)
4. Existing test coverage already targets these areas:
   - `Protocol/ProtocolParserTests.cs`
   - `JetStream/JetStreamMemoryStoreTests.cs`
   - `JetStream/StorageEngineTests.cs`
   - `Internal/DataStructures/SubscriptionIndexTests.cs`
   - `Internal/DataStructures/GenericSublistTests.cs`
5. Relevant files still contain unrelated TODO/stub markers; Batch 2 execution must prevent introducing any new stubs while tolerating pre-existing untouched markers.

## Assumptions

- Batch 1 dependency must be completed before Batch 2 status updates.
- Existing mapped behavior may be mostly implemented; Batch 2 likely requires a mix of parity fixes plus evidence-backed verification/status promotion.
- Because Batch 2 tracks 0 tests, verification must rely on related existing unit tests outside the batch.

## Approaches

### Approach A: Status-first verification only

Run related tests and update statuses if green; avoid code edits unless tests fail.

- Pros: Lowest churn, fast throughput.
- Cons: Risks hiding tracker/mapping drift or subtle behavior gaps not directly asserted.

### Approach B: Full parser/sublist/memstore rewrite for strict Go shape

Refactor methods and class placement to mirror Go structure exactly.

- Pros: Maximum structural parity.
- Cons: High regression risk and unnecessary code churn for a remainder batch.

### Approach C (Recommended): Hybrid parity hardening + evidence-driven status progression

Start with feature-by-feature verification loops; only add minimal targeted code/tests when a feature lacks direct proof or behavior diverges.

- Pros: Balances correctness, audit alignment, and delivery speed.
- Cons: Requires disciplined evidence collection and strict guardrails to avoid shallow verification.

## Recommended Design

### 1. Feature-Group Execution Model

Split Batch 2 into three groups:

- Parser group: `2588`, `2590`, `2591`
- Sublist group: `3446`, `3447`, `3448`
- MemStore group: `2068`, `2086`

Each group is implemented/verified independently with build and test gates before any status promotion.

### 2. Verification-First Feature Loop

For each feature:

1. Read mapped Go source range (`feature show <id>` + source file lines).
2. Confirm or implement C# parity in mapped target area.
3. Run focused related tests.
4. Run group-level build + test gates.
5. Only then promote statuses (`stub -> complete -> verified`) with evidence.

### 3. Mapping Drift Handling

If tracker expects a method shape that differs from existing .NET placement (for example parser methods under `ProtocolParser` instead of `ClientConnection`), use minimal compatibility wrappers or forwarding methods only when required by behavior/audit proof. Avoid broad refactors.

### 4. Evidence and Guardrails

- Mandatory stub scans on touched files after each group.
- Build gate after each group.
- Related test class gates before `verified`.
- Full checkpoint (build + full unit tests + commit) between tasks.

## Risks and Mitigations

1. **False confidence from pre-existing tests**  
   Mitigation: require per-feature evidence and add focused tests when a feature lacks direct assertions.

2. **Stub creep in large files**  
   Mitigation: baseline-plus-delta stub scan and hard failure on new markers.

3. **Over-refactoring for naming alignment**  
   Mitigation: additive wrappers only; preserve stable call paths.

4. **Status updates without proof**  
   Mitigation: enforce max-15 ID updates and attach command output evidence before promotion.

## Success Criteria

- All 8 Batch 2 features are implemented or confirmed behaviorally complete against Go intent.
- All related test gates pass for parser, sublist, and memstore areas.
- No new stub patterns are introduced in touched source or tests.
- Batch 2 feature statuses can be advanced to `verified` with explicit evidence and dependency compliance.