natsnet/docs/plans/2026-02-27-batch-8-store-interfaces-design.md

Batch 8 (Store Interfaces) Design

Date: 2026-02-27
Scope: Batch 8 planning only (27 features, 1 tracked test) for server/store.go parity.

Context Snapshot

Batch metadata (from PortTracker):

• Batch ID: 8
• Name: Store Interfaces
• Features: 27
• Tests: 1
• Dependencies: none
• Go source: server/store.go
• Current status: all 27 features and test 1751 are deferred

Targeted feature clusters:

• Stream-state codec/parsing and delete-block state helpers (IsEncodedStreamState, DecodeStreamState, DeleteRange.State, DeleteSlice.State)
• Consumer state encoding (encodeConsumerState)
• Enum JSON/string parity for RetentionPolicy, DiscardPolicy, StorageType, AckPolicy, ReplayPolicy, DeliverPolicy
• Store/runtime helpers (isOutOfSpaceErr, isClusterResetErr, StoreMsg.copy, bytesToString, stringToBytes, copyString, isPermissionError)

Tracked test in this batch:

• unit_test #1751 (TestJetStreamDirectGetUpToTime -> .NET: JetStreamEngineTests.JetStreamDirectGetUpToTime_ShouldSucceed)
• Depends on feature 3191 (bytesToString) plus already-verified features (325, 804, 2474, 2483, 3051)

Problem Statement

StoreTypes.cs already defines many store types and interfaces, but Batch 8 parity methods are still unverified/deferred. The risk is twofold:

1. Behavior gaps: binary decode/encode parity, enum JSON text parity, and byte/string helpers can silently diverge from Go semantics.
2. Audit/status drift: mapped feature names require explicit, test-backed evidence before transitioning from deferred to verified.

Constraints and Success Criteria

Constraints:

• .NET 10 + C# latest with nullable enabled
• xUnit 3 + Shouldly + NSubstitute only
• No stubs/fake tests for status promotion
• Batch/task grouping must stay <= ~20 features per task

Success criteria:

• All 27 feature mappings implemented or mapped with explicit wrappers/adapters and verified by related tests.
• One tracked test (1751) is either truly passing or explicitly deferred with concrete blocker evidence.
• PortTracker statuses updated in evidence-backed chunks with strict verification gates.

Approaches

Approach A: Minimal wrappers to satisfy mapped method names

Add thin wrappers only (for mapped member names), keep most logic unchanged.

• Pros: fast mapping closure.
• Cons: high risk of semantic mismatch; weak confidence in parity.

Approach B: Full parity refactor inside StoreTypes.cs

Rework all Batch 8 behavior directly in existing types and enums, including JSON handling and helpers.

• Pros: strongest parity in one place.
• Cons: high change surface in a core file; harder review/debug cycle.

Approach C (Recommended): Focused parity layer with targeted tests

Keep existing StoreTypes.cs types stable, add explicit parity methods/wrappers where needed, and add a dedicated test class that validates each mapped behavior from store.go.

• Pros: controlled change scope, strong evidence, easier audit and rollback.
• Cons: requires careful method-shape decisions for enum/string/JSON mappings.

Recommended Design

1. Production Code Layout

Primary touchpoint:

• dotnet/src/ZB.MOM.NatsNet.Server/JetStream/StoreTypes.cs

If needed to keep StoreTypes.cs readable, allow one focused helper file:

• dotnet/src/ZB.MOM.NatsNet.Server/JetStream/StoreParity.cs (or similarly named)

Design intent:

• Implement stream-state decode and encoding helpers with Go-equivalent error handling (ErrBadStreamStateEncoding, ErrCorruptStreamState).
• Add explicit state methods/parity wrappers for delete blocks and StoreMsg.copy semantics.
• Implement enum string/JSON parity through explicit methods and/or converters that preserve Go wire values ("limits", "new", "memory", etc.).
• Implement utility predicates/helpers exactly for Batch 8 semantics.

2. Test Design

Primary new test file:

• dotnet/tests/ZB.MOM.NatsNet.Server.Tests/JetStream/StoreTypesTests.cs

Test coverage split:

• Codec tests: encoded-stream header detection, decode success/failure paths, corrupt payload handling.
• Delete-block tests: State() and Range() behavior parity.
• Consumer-state encoding tests: deterministic structural assertions (header, key fields, pending/redelivery shape).
• Enum tests: string and JSON round-trip coverage, invalid input failures.
• Helper tests: out-of-space/cluster-reset predicates, byte/string conversion and copy isolation, permission error predicate.

Tracked test handling:

• Add/port JetStreamDirectGetUpToTime_ShouldSucceed in dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/JetStreamEngineTests.Impltests.cs only if it can be made real and executable.
• If environment/runtime dependencies block realism, keep #1751 deferred with explicit evidence and reason; do not add a fake-pass test.

3. Execution Slicing

Use two feature groups (both <=20 IDs):

• Group A (12 features): 3164,3165,3166,3168,3171,3187,3188,3189,3191,3192,3193,3194
• Group B (15 features): 3172,3173,3174,3175,3176,3177,3178,3179,3180,3181,3182,3183,3184,3185,3186

Then handle tracked test 1751 as a separate task.

4. Risks and Mitigations

1. Enum method-shape mismatch with C# enums vs Go methods
   Mitigation: use explicit parity methods/extensions and validate via tracker audit + tests.

2. Binary decode edge cases (varint parsing/corrupt payloads)
   Mitigation: table-driven tests using known-good and intentionally malformed byte payloads.

3. Existing ImplBacklog test quality is low
   Mitigation: strict anti-stub policy; only behavior-based assertions count toward verification.

4. Direct-get test may require broader server runtime not yet ported
   Mitigation: defer with concrete blocker evidence instead of fake implementation.

Design Decision

Choose Approach C: implement Batch 8 via a focused parity layer plus dedicated targeted tests, executed in two feature groups and one test task with strict status-evidence gates.