natsnet/docs/plans/2026-02-27-batch-27-jetstream-core-design.md

Batch 27 JetStream Core Design

Context

• Batch: 27 (JetStream Core)
• Scope: 82 features, 77 tests
• Dependencies: batches 5, 8, 19
• Primary Go source: golang/nats-server/server/jetstream.go
• PortTracker status snapshot (2026-02-27): batch 27 is pending

Batch 27 is the first full behavior layer for JetStream server lifecycle and per-account resource management. It spans server bootstrap/shutdown wiring, account-level JetStream enable/disable and usage tracking, limits enforcement, and config validation helpers consumed by later JetStream API and clustering batches.

Constraints and Success Criteria

Constraints

• No placeholder implementations or fake-pass tests.
• Dependency order is mandatory: batch 27 cannot start until batches 5, 8, and 19 are complete.
• Keep feature execution chunked to ~20 features per task group.
• Keep status updates evidence-based and chunked to max 15 IDs per batch-update call.
• Follow .NET standards: .NET 10, nullable, xUnit 3 + Shouldly + NSubstitute.

Success Criteria

• All 82 feature IDs are moved to verified or kept deferred with explicit blocker notes.
• All 77 test IDs are moved to verified or kept deferred with explicit blocker notes.
• No forbidden stub patterns in touched production or test files.
• Build and test gates pass at every checkpoint.

Approaches Considered

Approach A (Recommended): Incremental in-place behavior port with grouped feature waves

• Implement missing methods in existing core files (NatsServer partials, Account, JetStream/JsAccount core files).
• Execute five feature groups (max ~20 each), then port mapped tests in staged class waves.
• Promote statuses only after per-feature/per-test verification evidence.

Pros:

• Lowest structural risk.
• Best audit trace from Go line ranges to C# methods.
• Works well with strict status-evidence protocol.

Cons:

• Large diffs in a few high-churn files.

Approach B: Structural refactor first (convert types to partial files), then port behavior

• First split large classes into new partial files, then implement features.

Pros:

• Cleaner long-term organization.

Cons:

• Extra upfront churn before behavior parity.
• Harder to isolate regressions during a large dependency-heavy batch.

Approach C: Signature-first skeleton pass, fill behavior later

• Add methods quickly to satisfy compile, then return later to complete behavior.

Pros:

• Fast apparent progress.

Cons:

• Violates anti-stub requirements and creates false status inflation.

Decision: Approach A.

Proposed Design

1. Source Partitioning by Runtime Responsibility

Implement Batch 27 behavior in four logical zones:

• NatsServer JetStream lifecycle/config orchestration methods.
• Account JetStream account enrollment, limits assignment, account usage projections.
• JetStream engine-level limits/resource checks and global usage stats.
• JsAccount per-account synchronized usage, cluster usage sync, tier selection.

This mirrors the Go file layout while staying idiomatic in C#.

2. Feature Grouping Strategy (Max ~20/group)

Use five feature groups with contiguous IDs and behavior cohesion:

1. Group 1 (20): 1368-1387 — server enable/disable bootstrap, encryption setup, exports, account wiring
2. Group 2 (19): 1388,1389,1390,1391,1392,1394,1396,1397,1398,1399,1400,1401,1402,1403,1404,1405,1406,1407,1408 — runtime state flags/getters and account enable/update core
3. Group 3 (18): 1409-1426 — account usage snapshots and foundational limits helpers
4. Group 4 (17): 1427-1443 — jsAccount limits enforcement and stream resource reservation/release
5. Group 5 (8): 1444-1451 — dynamic config/validation/error helper tail

3. Test Porting Strategy

Port tests by class waves after core feature groups are green:

• Wave A (smaller cross-module classes, 19 tests): AccountTests, EventsHandlerTests, MonitoringHandlerTests, JetStreamVersioningTests, MqttHandlerTests, MessageTracerTests, ConcurrencyTests2, NatsServerTests
• Wave B (mid-size JetStream/storage classes, 17 tests): JetStreamFileStoreTests, NatsConsumerTests, ConcurrencyTests1
• Wave C (heavy class, 41 tests): JetStreamEngineTests in sub-batches; keep perf/benchmark-style tests deferred if they require unsupported harness/runtime shape.

4. Verification Model

The implementation plan defines a mandatory protocol with:

• Per-feature verification loop (read Go lines -> implement -> build/test evidence)
• Per-test verification loop (single-test pass evidence)
• Stub scan required after each group/class
• Build gate and test gate before status promotion
• Status updates in max-15 ID chunks
• Required checkpoints between tasks

5. Defer-Not-Stub Policy

If blocked by infrastructure/runtime gaps (cluster setup, benchmark harness, missing dependent behavior), keep item deferred with explicit reason in PortTracker; do not write placeholder code/tests.

Risks and Mitigations

• Risk: dependency batches still pending.
  • Mitigation: hard preflight gate before batch start 27.
• Risk: large JetStreamEngine test class can hide shallow ports.
  • Mitigation: single-test evidence + assertion density checks + periodic class gates.
• Risk: status inflation without proof.
  • Mitigation: max-15 update chunks and evidence checklist per update.

Design Approval Note

This design is based on the explicit constraints in your request and current repository state. The implementation plan materializes this design into executable, checkpointed tasks without running any batch work.