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.