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

Batch 19 Accounts Core Design

Context

• Batch: 19 (Accounts Core)
• Scope: 92 features, 9 tests
• Dependencies: Batches 16, 18
• Primary Go reference: golang/nats-server/server/accounts.go
• Primary .NET target: dotnet/src/ZB.MOM.NatsNet.Server/Accounts/Account.cs

Batch 19 is the largest non-JetStream account behavior surface: service import/export wiring, reverse reply tracking, activation and issuer checks, leaf-node cluster bookkeeping, and account-level message tracing hooks.

Constraints

• No stubs for feature or test completion.
• Port behavior from Go intent, not line-for-line syntax.
• Keep batch execution chunked (max ~20 features per task group).
• Keep PortTracker status updates evidence-based and chunked (max 15 IDs per update call).
• Dependencies 16 and 18 must be complete before execution starts.

Approaches Considered

Approach A (Recommended): Incremental Port in Existing Account.cs + Backlog Test Hardening

• Keep Account in its current file and add missing methods in ordered regions.
• Use feature groups aligned to Go line ranges and behavior domains.
• Promote features stub -> complete during implementation; only promote to verified after related tests are green.
• Port only Batch 19 test IDs in existing backlog classes first, then run broader account-related suite gates.

Pros:

• Lowest structural risk and least file churn.
• Preserves current locking/state conventions already used in Account.cs.
• Easier diff review against Go line ranges and PortTracker IDs.

Cons:

• Account.cs grows further until later refactor batch.

Approach B: Convert Account to Partial Class and Split by Domain During Port

• First convert Account to partial, then create files like Account.ServiceImports.cs, Account.StreamImports.cs, etc.
• Port methods into these new files while adding tests.

Pros:

• Cleaner file organization.
• Better long-term readability.

Cons:

• Larger structural change while behavior is still moving.
• Higher merge risk and harder one-to-one audit against existing method maps.

Approach C: Minimal Compile-First Skeletons, Fill Later

• Add signatures and placeholders quickly to satisfy compile, then fill behavior in later passes.

Pros:

• Fast initial progress indicators.

Cons:

• Violates anti-stub requirements.
• High risk of false progress and broken verification integrity.

Decision: Approach A.

Proposed Architecture

1. Keep Account Behavior Localized to Account.cs

• Implement missing Batch 19 methods directly in Account.cs.
• Only modify AccountTypes.cs when a missing helper type/field is required by real behavior.
• Avoid cross-module refactors while porting this batch.

2. Feature Grouping Strategy

Use five implementation groups with contiguous, behavior-aligned IDs:

1. Group 1 (17 features): identity, trace destination, connection/interest, leaf cluster registration, base service export registration
2. Group 2 (20 features): latency tracking send paths + service import cycle checks + pending response counters
3. Group 3 (20 features): service import map mutation, reverse response tracking, internal subscription lifecycle, response wildcard processing
4. Group 4 (20 features): service reply generation, thresholds, response import wiring, stream import/export add and authorization checks
5. Group 5 (15 features): activation expiration paths, issuer trust checks, bearer/expiration handling, external auth helpers

Each group is independently buildable and testable.

3. Test Porting Strategy for the 9 Batch Tests

Port only these IDs in backlog classes:

• 81, 82, 95 -> ImplBacklog/AccountTests.Impltests.cs
• 658, 666 -> ImplBacklog/GatewayHandlerTests.Impltests.cs
• 1935, 1952, 1955 -> ImplBacklog/LeafNodeHandlerTests.Impltests.cs
• 2359 -> ImplBacklog/MessageTracerTests.Impltests.cs

Replace placeholder tests with behavioral assertions derived from Go test intent.

4. Verification-First Status Flow

• During coding: move feature IDs to stub.
• After implementation + build + related tests: move to complete.
• After full related test gate and evidence capture: move to verified.
• If blocked: keep deferred with explicit reason (no placeholder code).

Error Handling and Concurrency Design Notes

• Preserve lock discipline already used in Account.cs (_mu, _lmu, _sqmu, _eventIdsMu).
• Do not widen lock scopes unless required for correctness parity with Go behavior.
• Preserve existing exception-return pattern used by account APIs (Exception? return for validation paths).
• Preserve current JWT placeholder boundaries; if JWT-infra dependency is missing, defer with reason instead of stubbing.

Risks and Mitigations

• Risk: long Account.cs diffs become hard to review.
  • Mitigation: strict feature grouping + per-group checkpoints + frequent commits.
• Risk: false-positive "passing" backlog tests.
  • Mitigation: anti-stub scans and required per-test behavioral assertions.
• Risk: status inflation without evidence.
  • Mitigation: max-15 ID update chunks + required command output evidence per chunk.

Success Criteria

• All 92 Batch 19 feature IDs are verified or explicitly deferred with reason.
• All 9 Batch 19 test IDs are verified or explicitly deferred with reason.
• No forbidden stub patterns in touched source/tests.
• Full build and required test gates pass at each checkpoint.