natsdotnet/docs/plans/2026-02-23-jetstream-deep-operational-parity-design.md

# JetStream Deep Operational Parity Design

**Date:** 2026-02-23  
**Status:** Approved  
**Scope:** Identify and close remaining JetStream deep operational parity gaps versus Go, including behavior-level semantics, storage durability, RAFT/cluster behavior, and documentation drift reconciliation.

## 1. Architecture and Scope Boundary

### Scope definition
This cycle is JetStream-focused and targets deep operational parity:

1. Stream runtime semantics
2. Consumer runtime/state machine semantics
3. Storage durability semantics
4. RAFT/network and JetStream clustering semantics
5. Documentation/evidence reconciliation

`JETSTREAM (internal)` is treated as implemented behavior (code + tests present). Any stale doc line stating it is unimplemented is handled as documentation drift, not a re-implementation target.

### Parity control model
Each feature area is tracked with a truth matrix:

1. Behavior
- Go-equivalent runtime behavior exists in observable server operation.

2. Tests
- Contract-positive plus negative/edge tests validate behavior and detect regressions beyond hook-level checks.

3. Docs
- `differences.md` and parity artifacts accurately reflect validated behavior.

A feature closes only when Behavior + Tests + Docs are all complete.

### Ordered implementation layers
1. Stream runtime semantics
2. Consumer state machine semantics
3. Storage durability semantics
4. RAFT and cluster governance semantics
5. Documentation synchronization

## 2. Component Plan

### A. Stream runtime semantics
Primary files:
- `src/NATS.Server/JetStream/StreamManager.cs`
- `src/NATS.Server/JetStream/Models/StreamConfig.cs`
- `src/NATS.Server/JetStream/Publish/JetStreamPublisher.cs`
- `src/NATS.Server/JetStream/Publish/PublishPreconditions.cs`
- `src/NATS.Server/JetStream/Api/Handlers/StreamApiHandlers.cs`
- `src/NATS.Server/JetStream/Validation/JetStreamConfigValidator.cs`

Focus:
- retention semantics (`Limits/Interest/WorkQueue`) under live publish/delete flows
- `MaxAge`, `MaxMsgsPer`, `MaxMsgSize`, dedupe-window semantics under mixed workloads
- guard behavior (`sealed`, `deny_delete`, `deny_purge`) with contract-accurate errors
- runtime (not parse-only) behavior for transform/republish/direct-related features

### B. Consumer runtime/state machine semantics
Primary files:
- `src/NATS.Server/JetStream/ConsumerManager.cs`
- `src/NATS.Server/JetStream/Consumers/AckProcessor.cs`
- `src/NATS.Server/JetStream/Consumers/PullConsumerEngine.cs`
- `src/NATS.Server/JetStream/Consumers/PushConsumerEngine.cs`
- `src/NATS.Server/JetStream/Models/ConsumerConfig.cs`
- `src/NATS.Server/JetStream/Api/Handlers/ConsumerApiHandlers.cs`

Focus:
- deliver-policy start resolution and cursor transitions
- ack floor and redelivery determinism (`AckPolicy.*`, backoff, max-deliver)
- flow control, rate limiting, replay timing semantics across longer scenarios

### C. Storage durability semantics
Primary files:
- `src/NATS.Server/JetStream/Storage/FileStore.cs`
- `src/NATS.Server/JetStream/Storage/FileStoreBlock.cs`
- `src/NATS.Server/JetStream/Storage/FileStoreOptions.cs`
- `src/NATS.Server/JetStream/Storage/IStreamStore.cs`
- `src/NATS.Server/JetStream/Storage/MemStore.cs`

Focus:
- durable block/index invariants under restart and prune/rewrite cycles
- compression/encryption behavior from transform stubs to parity-meaningful persistence semantics
- TTL and index consistency guarantees for large and long-running data sets

### D. RAFT and JetStream cluster semantics
Primary files:
- `src/NATS.Server/Raft/RaftNode.cs`
- `src/NATS.Server/Raft/RaftReplicator.cs`
- `src/NATS.Server/Raft/RaftTransport.cs`
- `src/NATS.Server/Raft/RaftRpcContracts.cs`
- `src/NATS.Server/JetStream/Cluster/JetStreamMetaGroup.cs`
- `src/NATS.Server/JetStream/Cluster/StreamReplicaGroup.cs`
- `src/NATS.Server/JetStream/Cluster/AssetPlacementPlanner.cs`
- integration touchpoints in `src/NATS.Server/NatsServer.cs`

Focus:
- move from hook-level consensus behaviors to term/quorum-driven outcomes
- snapshot transfer and membership semantics affecting real commit/placement behavior
- cross-cluster JetStream behavior validated beyond counter-style forwarding checks

### E. Evidence and documentation reconciliation
Primary files:
- `differences.md`
- `docs/plans/2026-02-23-jetstream-remaining-parity-map.md`
- `docs/plans/2026-02-23-jetstream-remaining-parity-verification.md`

Focus:
- remove stale contradictory lines and align notes with verified implementation state
- keep all parity claims traceable to tests and behavior evidence

## 3. Data Flow and Behavioral Contracts

1. Publish path contract
- precondition checks occur before persistence mutation
- stream policy outcomes are atomic from client perspective
- no partial state exposure on failed publish paths

2. Consumer path contract
- deterministic cursor initialization and progression
- ack/redelivery/backoff semantics form a single coherent state machine
- push/pull engines preserve contract parity under sustained load and restart boundaries

3. Storage contract
- persisted data and indices roundtrip across restarts without sequence/index drift
- pruning, ttl, and limit enforcement preserve state invariants (`first/last/messages/bytes`)
- compression/encryption boundaries are reversible and version-safe

4. RAFT/cluster contract
- append/commit behavior is consensus-gated (term/quorum aware)
- heartbeat and snapshot mechanics drive observable follower convergence
- placement/governance decisions reflect committed cluster state

5. Documentation contract
- JetStream table rows and summary notes in `differences.md` must agree
- `JETSTREAM (internal)` status remains `Y` with explicit verification evidence

## 4. Error Handling, Testing Strategy, and Completion Gates

### Error handling
1. Keep JetStream-specific error semantics and codes intact.
2. Fail closed on durability/consensus invariant breaches.
3. Reject partial cluster mutations when consensus prerequisites fail.

### Test strategy
1. Per feature area: contract-positive + edge/failure test.
2. Persistence features: restart/recovery tests are mandatory.
3. Replace hook-level “counter” tests with behavior-real integration tests for deep semantics.
4. Keep targeted suites per layer plus cross-layer integration scenarios.

### Completion gates
1. Behavior gate: deep JetStream operational parity gaps closed or explicitly blocked with evidence.
2. Test gate: focused suites and full suite pass.
3. Docs gate: parity docs reflect actual validated behavior; stale contradictions removed.
4. Drift gate: explicit verification that internal JetStream client remains implemented and documented as `Y`.