Improve XML documentation coverage across src modules and sync generated analysis artifacts.

docs/plans/2026-03-14-dtp-parser-design.md

@@ -0,0 +1,75 @@
+# dotTrace DTP Parser Design
+
+**Goal:** Build a repository-local tool that starts from a raw dotTrace `.dtp` snapshot family and emits machine-readable JSON call-tree data suitable for LLM-driven hotspot analysis.
+
+**Context**
+
+The target snapshot format is JetBrains dotTrace multi-file storage:
+
+- `snapshot.dtp` is the index/manifest.
+- `snapshot.dtp.0000`, `.0001`, and related files hold the storage sections.
+- `snapshot.dtp.States` holds UI state and is not sufficient for call-tree analysis.
+
+The internal binary layout is not publicly specified. A direct handwritten decoder would be brittle and expensive to maintain. The machine already has dotTrace installed, and the shipped JetBrains assemblies expose snapshot storage, metadata, and performance call-tree readers. The design therefore uses dotTrace’s local runtime libraries as the authoritative decoder while still starting from the raw `.dtp` files.
+
+**Architecture**
+
+Two layers:
+
+1. A small .NET helper opens the raw snapshot, reads the performance DFS call-tree and node payload sections, resolves function names through the profiler metadata section, and emits JSON.
+2. A Python CLI is the user-facing entrypoint. It validates input, builds or reuses the helper, runs it, and writes JSON to stdout or a file.
+
+This keeps the user workflow Python-first while using the only reliable decoder available for the undocumented snapshot format.
+
+**Output schema**
+
+The JSON should support both direct consumption and downstream summarization:
+
+- `snapshot`: source path, thread count, node count, payload type.
+- `thread_roots`: thread root metadata.
+- `call_tree`: synthetic root with recursive children.
+- `hotspots`: flat top lists for inclusive and exclusive time.
+
+Each node should include:
+
+- `id`: stable offset-based identifier.
+- `name`: resolved method or synthetic node name.
+- `kind`: `root`, `thread`, `method`, or `special`.
+- `inclusive_time`
+- `exclusive_time`
+- `call_count`
+- `thread_name` when relevant
+- `children`
+
+**Resolution strategy**
+
+Method names are resolved from the snapshot’s metadata section:
+
+- Use the snapshot’s FUID-to-metadata converter.
+- Map `FunctionUID` to `FunctionId`.
+- Resolve `MetadataId`.
+- Read function and class data with `MetadataSectionHelpers`.
+
+Synthetic and special frames fall back to explicit labels instead of opaque numeric values where possible.
+
+**Error handling**
+
+The tool should fail loudly for the cases that matter:
+
+- Missing dotTrace assemblies.
+- Unsupported snapshot layout.
+- Missing metadata sections.
+- Helper build or execution failure.
+
+Errors should name the failing stage so the Python wrapper can surface actionable messages.
+
+**Testing**
+
+Use the checked-in sample snapshot at `snapshots/js-ordered-consume.dtp` for an end-to-end test:
+
+- JSON parses successfully.
+- The root contains thread children.
+- Hotspot lists are populated.
+- At least one non-special method name is resolved.
+
+This is enough to verify the extraction path without freezing the entire output.

docs/plans/2026-03-14-dtp-parser.md

@@ -0,0 +1,186 @@
+# dotTrace DTP Parser Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add a Python-first tool that reads a raw dotTrace `.dtp` snapshot family and emits JSON call-tree and hotspot data for LLM analysis.
+
+**Architecture:** A small .NET helper uses JetBrains’ local dotTrace assemblies to decode snapshot storage, performance call-tree nodes, payloads, and metadata. A Python wrapper validates input, builds the helper if needed, runs it, and writes the resulting JSON.
+
+**Tech Stack:** Python 3 standard library, .NET 10 console app, local JetBrains dotTrace assemblies, `unittest`
+
+---
+
+### Task 1: Add the failing end-to-end test
+
+**Files:**
+- Create: `tools/tests/test_dtp_parser.py`
+
+**Step 1: Write the failing test**
+
+Write a `unittest` test that runs:
+
+```bash
+python3 tools/dtp_parse.py snapshots/js-ordered-consume.dtp --stdout
+```
+
+and asserts:
+
+- exit code is `0`
+- stdout is valid JSON
+- `call_tree.children` is non-empty
+- `hotspots.inclusive` is non-empty
+- at least one node name is not marked as special
+
+**Step 2: Run test to verify it fails**
+
+Run: `python3 -m unittest tools.tests.test_dtp_parser -v`
+
+Expected: FAIL because `tools/dtp_parse.py` does not exist yet.
+
+**Step 3: Commit**
+
+```bash
+git add tools/tests/test_dtp_parser.py
+git commit -m "test: add dtp parser end-to-end expectation"
+```
+
+### Task 2: Implement the .NET snapshot extractor
+
+**Files:**
+- Create: `tools/DtpSnapshotExtractor/DtpSnapshotExtractor.csproj`
+- Create: `tools/DtpSnapshotExtractor/Program.cs`
+
+**Step 1: Write the minimal implementation**
+
+Implement a console app that:
+
+- accepts snapshot path and optional output path
+- opens the snapshot through JetBrains snapshot storage
+- constructs performance call-tree and payload readers
+- resolves method names via metadata sections
+- builds a JSON object with root tree, thread roots, and hotspot lists
+- writes JSON to stdout or output file
+
+**Step 2: Run helper directly**
+
+Run:
+
+```bash
+dotnet run --project tools/DtpSnapshotExtractor -- snapshots/js-ordered-consume.dtp
+```
+
+Expected: JSON is emitted successfully.
+
+**Step 3: Commit**
+
+```bash
+git add tools/DtpSnapshotExtractor/DtpSnapshotExtractor.csproj tools/DtpSnapshotExtractor/Program.cs
+git commit -m "feat: add dottrace snapshot extractor helper"
+```
+
+### Task 3: Implement the Python entrypoint
+
+**Files:**
+- Create: `tools/dtp_parse.py`
+
+**Step 1: Write the minimal implementation**
+
+Implement a CLI that:
+
+- accepts snapshot path
+- supports `--out` and `--stdout`
+- checks that dotTrace assemblies exist in the local install
+- runs `dotnet run --project tools/DtpSnapshotExtractor -- <snapshot>`
+- forwards JSON output
+
+**Step 2: Run the wrapper**
+
+Run:
+
+```bash
+python3 tools/dtp_parse.py snapshots/js-ordered-consume.dtp --stdout
+```
+
+Expected: JSON is emitted successfully.
+
+**Step 3: Commit**
+
+```bash
+git add tools/dtp_parse.py
+git commit -m "feat: add python dtp parsing entrypoint"
+```
+
+### Task 4: Make the test pass and tighten output
+
+**Files:**
+- Modify: `tools/DtpSnapshotExtractor/Program.cs`
+- Modify: `tools/dtp_parse.py`
+- Modify: `tools/tests/test_dtp_parser.py`
+
+**Step 1: Run the failing test**
+
+Run: `python3 -m unittest tools.tests.test_dtp_parser -v`
+
+Expected: FAIL with an output-schema or execution issue.
+
+**Step 2: Fix the minimal failing behavior**
+
+Adjust:
+
+- special-node labeling
+- JSON schema stability
+- helper invocation details
+- fallback behavior for unresolved metadata
+
+**Step 3: Re-run the test**
+
+Run: `python3 -m unittest tools.tests.test_dtp_parser -v`
+
+Expected: PASS
+
+**Step 4: Commit**
+
+```bash
+git add tools/DtpSnapshotExtractor/Program.cs tools/dtp_parse.py tools/tests/test_dtp_parser.py
+git commit -m "test: verify dtp parser output"
+```
+
+### Task 5: Final verification
+
+**Files:**
+- Modify: none unless fixes are required
+
+**Step 1: Run end-to-end extraction**
+
+Run:
+
+```bash
+python3 tools/dtp_parse.py snapshots/js-ordered-consume.dtp --out /tmp/js-ordered-consume-calltree.json
+```
+
+Expected: JSON file is created.
+
+**Step 2: Run test suite**
+
+Run:
+
+```bash
+python3 -m unittest tools.tests.test_dtp_parser -v
+```
+
+Expected: PASS
+
+**Step 3: Inspect a hotspot sample**
+
+Confirm the JSON contains:
+
+- resolved method names
+- inclusive and exclusive hotspot lists
+- nested thread call trees
+
+**Step 4: Commit**
+
+```bash
+git add docs/plans/2026-03-14-dtp-parser-design.md docs/plans/2026-03-14-dtp-parser.md
+git commit -m "docs: add dtp parser design and plan"
+```

dottrace.md

@@ -196,6 +196,83 @@ Open `.dtp` / `.dtt` snapshot files in:
 open /Users/dohertj2/Applications/dotTrace.app --args ./snapshots/nats-sampling.dtp
 ```
 
+## Parsing Raw `.dtp` Snapshots To JSON
+
+The repository includes a Python-first parser for raw dotTrace sampling and tracing snapshots:
+
+- Python entrypoint: [tools/dtp_parse.py](/Users/dohertj2/Desktop/natsdotnet/tools/dtp_parse.py)
+- .NET helper: [tools/DtpSnapshotExtractor/Program.cs](/Users/dohertj2/Desktop/natsdotnet/tools/DtpSnapshotExtractor/Program.cs)
+
+The parser starts from the raw `.dtp` snapshot family and emits machine-readable JSON for call-tree and hotspot analysis. It uses the locally installed dotTrace assemblies to decode the snapshot format.
+
+### Prerequisites
+
+- `python3`
+- `.NET 10 SDK`
+- dotTrace installed at `/Users/dohertj2/Applications/dotTrace.app`
+
+If dotTrace is installed elsewhere, set `DOTTRACE_APP_DIR` to the `Contents/DotFiles` directory:
+
+```bash
+export DOTTRACE_APP_DIR="/path/to/dotTrace.app/Contents/DotFiles"
+```
+
+### Print JSON to stdout
+
+```bash
+python3 tools/dtp_parse.py snapshots/js-ordered-consume.dtp --stdout
+```
+
+### Write JSON to a file
+
+```bash
+python3 tools/dtp_parse.py snapshots/js-ordered-consume.dtp \
+  --out /tmp/js-ordered-consume-calltree.json
+```
+
+### Output shape
+
+The generated JSON contains:
+
+- `snapshot` — source path, payload type, thread count, node count
+- `threadRoots` — top-level thread roots with inclusive time
+- `callTree` — nested call tree rooted at a synthetic `<root>`
+- `hotspots` — flat `inclusive` and `exclusive` method lists
+
+Hotspot entries are method-first. Synthetic frames such as thread roots are excluded from the hotspot lists so the output is easier to feed into an LLM for slowdown analysis.
+
+### Typical analysis workflow
+
+1. Capture a snapshot with `dottrace`.
+2. Convert the raw `.dtp` snapshot to JSON:
+
+```bash
+python3 tools/dtp_parse.py snapshots/nats-sampling.dtp \
+  --out /tmp/nats-sampling-calltree.json
+```
+
+3. Inspect the top hotspots:
+
+```bash
+python3 - <<'PY'
+import json
+with open('/tmp/nats-sampling-calltree.json') as f:
+    data = json.load(f)
+print('Top inclusive:', data['hotspots']['inclusive'][0]['name'])
+print('Top exclusive:', data['hotspots']['exclusive'][0]['name'])
+PY
+```
+
+4. Feed the JSON into downstream tooling or an LLM to walk the call tree and identify expensive paths.
+
+### Verification
+
+Run the parser test with:
+
+```bash
+python3 -m unittest tools.tests.test_dtp_parser -v
+```
+
 ## Exit Codes
 
 | Code | Meaning |
@@ -212,3 +289,4 @@ open /Users/dohertj2/Applications/dotTrace.app --args ./snapshots/nats-sampling.
   ```bash
   mkdir -p snapshots
   ```
+- The parser currently targets raw `.dtp` snapshots. Timeline `.dtt` snapshots are still intended for the GUI viewer.

src/NATS.Server/Auth/AccountConfig.cs

@@ -2,8 +2,11 @@ namespace NATS.Server.Auth;
 
 public sealed class AccountConfig
 {
+    /// <summary>Maximum concurrent client connections allowed for this account (0 = unlimited).</summary>
     public int MaxConnections { get; init; }      // 0 = unlimited
+    /// <summary>Maximum subscriptions per client/account context (0 = unlimited).</summary>
     public int MaxSubscriptions { get; init; }    // 0 = unlimited
+    /// <summary>Default publish/subscribe permissions applied to users in this account.</summary>
     public Permissions? DefaultPermissions { get; init; }
 
     /// <summary>Service and stream exports from this account.</summary>
@@ -19,7 +22,9 @@ public sealed class AccountConfig
 /// </summary>
 public sealed class ExportDefinition
 {
+    /// <summary>Service subject exported to other accounts.</summary>
     public string? Service { get; init; }
+    /// <summary>Stream subject exported to other accounts.</summary>
     public string? Stream { get; init; }
 
     /// <summary>Optional latency tracking subject (e.g. "latency.svc.echo").</summary>
@@ -36,9 +41,14 @@ public sealed class ExportDefinition
 /// </summary>
 public sealed class ImportDefinition
 {
+    /// <summary>Remote account name for imported service mappings.</summary>
     public string? ServiceAccount { get; init; }
+    /// <summary>Remote service subject imported from <see cref="ServiceAccount"/>.</summary>
     public string? ServiceSubject { get; init; }
+    /// <summary>Remote account name for imported stream mappings.</summary>
     public string? StreamAccount { get; init; }
+    /// <summary>Remote stream subject imported from <see cref="StreamAccount"/>.</summary>
     public string? StreamSubject { get; init; }
+    /// <summary>Local remapped subject for imported services/streams.</summary>
     public string? To { get; init; }
 }

src/NATS.Server/Auth/AccountImportExport.cs

@@ -15,6 +15,9 @@ public static class AccountImportExport
     /// Returns true if following service imports from <paramref name="from"/>
     /// eventually leads back to <paramref name="to"/>.
     /// </summary>
+    /// <param name="from">Starting account whose service-import edges are traversed.</param>
+    /// <param name="to">Target account that would indicate an import cycle if reached.</param>
+    /// <param name="visited">Visited account-name set used to avoid infinite graph recursion.</param>
     public static bool DetectCycle(Account from, Account to, HashSet<string>? visited = null)
     {
         ArgumentNullException.ThrowIfNull(from);
@@ -48,6 +51,9 @@ public static class AccountImportExport
     /// <summary>
     /// Validates that the import is authorized and does not create a cycle.
     /// </summary>
+    /// <param name="importingAccount">Account requesting to import a service.</param>
+    /// <param name="exportingAccount">Account exporting the requested service subject.</param>
+    /// <param name="exportSubject">Exported service subject being imported.</param>
     /// <exception cref="UnauthorizedAccessException">Thrown when the importing account is not authorized.</exception>
     /// <exception cref="InvalidOperationException">Thrown when the import would create a cycle.</exception>
     public static void ValidateImport(Account importingAccount, Account exportingAccount, string exportSubject)

src/NATS.Server/Auth/AuthExtensionOptions.cs

@@ -2,6 +2,11 @@ namespace NATS.Server.Auth;
 
 public interface IExternalAuthClient
 {
+    /// <summary>
+    /// Requests an allow/deny decision from an external authentication provider.
+    /// </summary>
+    /// <param name="request">Credential material and identity hints from the client connection.</param>
+    /// <param name="ct">Cancellation token bound to auth timeout and connection lifecycle.</param>
     Task<ExternalAuthDecision> AuthorizeAsync(ExternalAuthRequest request, CancellationToken ct);
 }
 
@@ -19,14 +24,36 @@ public record ExternalAuthDecision(
 
 public sealed class ExternalAuthOptions
 {
+    /// <summary>
+    /// Gets or sets a value indicating whether external auth callouts are enabled.
+    /// </summary>
     public bool Enabled { get; set; }
+
+    /// <summary>
+    /// Gets or sets the timeout budget for each external auth decision request.
+    /// </summary>
     public TimeSpan Timeout { get; set; } = TimeSpan.FromSeconds(2);
+
+    /// <summary>
+    /// Gets or sets the client implementation responsible for external auth decisions.
+    /// </summary>
     public IExternalAuthClient? Client { get; set; }
 }
 
 public sealed class ProxyAuthOptions
 {
+    /// <summary>
+    /// Gets or sets a value indicating whether trusted-proxy authentication mode is enabled.
+    /// </summary>
     public bool Enabled { get; set; }
+
+    /// <summary>
+    /// Gets or sets the required username prefix marking identities provided by a trusted proxy.
+    /// </summary>
     public string UsernamePrefix { get; set; } = "proxy:";
+
+    /// <summary>
+    /// Gets or sets the default account to assign when proxy-authenticated users omit one.
+    /// </summary>
     public string? Account { get; set; }
 }

src/NATS.Server/Auth/AuthResult.cs

@@ -2,10 +2,33 @@ namespace NATS.Server.Auth;
 
 public sealed class AuthResult
 {
+    /// <summary>
+    /// Gets the resolved client identity that successfully authenticated.
+    /// </summary>
     public required string Identity { get; init; }
+
+    /// <summary>
+    /// Gets the account name assigned to the authenticated identity.
+    /// </summary>
     public string? AccountName { get; init; }
+
+    /// <summary>
+    /// Gets effective publish/subscribe permissions applied to the connection.
+    /// </summary>
     public Permissions? Permissions { get; init; }
+
+    /// <summary>
+    /// Gets the credential expiry timestamp after which the connection should be considered invalid.
+    /// </summary>
     public DateTimeOffset? Expiry { get; init; }
+
+    /// <summary>
+    /// Gets the maximum number of JetStream streams permitted for this identity.
+    /// </summary>
     public int MaxJetStreamStreams { get; init; }
+
+    /// <summary>
+    /// Gets the JetStream tier assigned for quota enforcement.
+    /// </summary>
     public string? JetStreamTier { get; init; }
 }

src/NATS.Server/Auth/AuthService.cs

@@ -15,7 +15,14 @@ public sealed class AuthService
     private readonly string? _noAuthUser;
     private readonly Dictionary<string, User>? _usersMap;
 
+    /// <summary>
+    /// Gets a value indicating whether any authentication mechanism is configured.
+    /// </summary>
     public bool IsAuthRequired { get; }
+
+    /// <summary>
+    /// Gets a value indicating whether the protocol must issue a nonce challenge.
+    /// </summary>
     public bool NonceRequired { get; }
 
     private AuthService(List<IAuthenticator> authenticators, bool authRequired, bool nonceRequired,
@@ -28,6 +35,10 @@ public sealed class AuthService
         _usersMap = usersMap;
     }
 
+    /// <summary>
+    /// Builds an authentication service from server options and configured auth sources.
+    /// </summary>
+    /// <param name="options">Server options containing static users, tokens, NKeys, and auth extensions.</param>
     public static AuthService Build(NatsOptions options)
     {
         var authenticators = new List<IAuthenticator>();
@@ -97,6 +108,10 @@ public sealed class AuthService
         return new AuthService(authenticators, authRequired, nonceRequired, options.NoAuthUser, usersMap);
     }
 
+    /// <summary>
+    /// Attempts to authenticate a client CONNECT context against configured authenticators.
+    /// </summary>
+    /// <param name="context">Client auth context extracted from CONNECT and transport metadata.</param>
     public AuthResult? Authenticate(ClientAuthContext context)
     {
         if (!IsAuthRequired)
@@ -145,6 +160,9 @@ public sealed class AuthService
         return new AuthResult { Identity = _noAuthUser };
     }
 
+    /// <summary>
+    /// Generates cryptographically strong nonce bytes for NKey/JWT signature challenges.
+    /// </summary>
     public byte[] GenerateNonce()
     {
         Span<byte> raw = stackalloc byte[11];
@@ -152,6 +170,13 @@ public sealed class AuthService
         return raw.ToArray();
     }
 
+    /// <summary>
+    /// Validates MQTT username/password fields against configured MQTT auth settings.
+    /// </summary>
+    /// <param name="configuredUsername">Username configured on the server for MQTT auth.</param>
+    /// <param name="configuredPassword">Password configured on the server for MQTT auth.</param>
+    /// <param name="providedUsername">Username supplied by the connecting MQTT client.</param>
+    /// <param name="providedPassword">Password supplied by the connecting MQTT client.</param>
     public static bool ValidateMqttCredentials(
         string? configuredUsername,
         string? configuredPassword,
@@ -165,6 +190,10 @@ public sealed class AuthService
             && string.Equals(configuredPassword, providedPassword, StringComparison.Ordinal);
     }
 
+    /// <summary>
+    /// Encodes nonce bytes into URL-safe base64 format used by NATS auth challenges.
+    /// </summary>
+    /// <param name="nonce">Raw nonce bytes generated for the challenge.</param>
     public string EncodeNonce(byte[] nonce)
     {
         return Convert.ToBase64String(nonce)

src/NATS.Server/Auth/ClientPermissions.cs

@@ -16,6 +16,10 @@ public sealed class ClientPermissions : IDisposable
         _responseTracker = responseTracker;
     }
 
+    /// <summary>
+    /// Builds a runtime client-permissions evaluator from account/user permission config.
+    /// </summary>
+    /// <param name="permissions">Permission configuration from auth claims or static config.</param>
     public static ClientPermissions? Build(Permissions? permissions)
     {
         if (permissions == null)
@@ -33,8 +37,11 @@ public sealed class ClientPermissions : IDisposable
         return new ClientPermissions(pub, sub, responseTracker);
     }
 
+    /// <summary>Optional tracker used to authorize dynamic response subjects.</summary>
     public ResponseTracker? ResponseTracker => _responseTracker;
 
+    /// <summary>Determines whether publishing to the given subject is permitted.</summary>
+    /// <param name="subject">Publish subject being authorized for the client.</param>
     public bool IsPublishAllowed(string subject)
     {
         if (_publish == null)
@@ -56,6 +63,9 @@ public sealed class ClientPermissions : IDisposable
         return allowed;
     }
 
+    /// <summary>Determines whether subscribing to the given subject/queue is permitted.</summary>
+    /// <param name="subject">Subscription subject being authorized.</param>
+    /// <param name="queue">Optional queue group name for queue-subscription checks.</param>
     public bool IsSubscribeAllowed(string subject, string? queue = null)
     {
         if (_subscribe == null)
@@ -67,6 +77,8 @@ public sealed class ClientPermissions : IDisposable
         return true;
     }
 
+    /// <summary>Determines whether delivering a message on the subject is permitted.</summary>
+    /// <param name="subject">Delivery subject evaluated against deny rules.</param>
     public bool IsDeliveryAllowed(string subject)
     {
         if (_subscribe == null)
@@ -74,6 +86,7 @@ public sealed class ClientPermissions : IDisposable
         return _subscribe.IsDeliveryAllowed(subject);
     }
 
+    /// <summary>Disposes permission resources used by this evaluator.</summary>
     public void Dispose()
     {
         _publish?.Dispose();
@@ -92,6 +105,10 @@ public sealed class PermissionSet : IDisposable
         _deny = deny;
     }
 
+    /// <summary>
+    /// Builds allow/deny sublists from a subject-permission definition.
+    /// </summary>
+    /// <param name="permission">Allow/deny subject rules.</param>
     public static PermissionSet? Build(SubjectPermission? permission)
     {
         if (permission == null)
@@ -123,6 +140,8 @@ public sealed class PermissionSet : IDisposable
         return new PermissionSet(allow, deny);
     }
 
+    /// <summary>Checks whether a subject passes allow/deny evaluation.</summary>
+    /// <param name="subject">Subject candidate to evaluate against allow and deny lists.</param>
     public bool IsAllowed(string subject)
     {
         bool allowed = true;
@@ -142,6 +161,8 @@ public sealed class PermissionSet : IDisposable
         return allowed;
     }
 
+    /// <summary>Checks whether a subject is explicitly denied.</summary>
+    /// <param name="subject">Subject candidate evaluated against deny entries.</param>
     public bool IsDenied(string subject)
     {
         if (_deny == null) return false;
@@ -149,6 +170,8 @@ public sealed class PermissionSet : IDisposable
         return result.PlainSubs.Length > 0 || result.QueueSubs.Length > 0;
     }
 
+    /// <summary>Checks delivery permission using deny-list semantics.</summary>
+    /// <param name="subject">Subject being delivered to a subscriber.</param>
     public bool IsDeliveryAllowed(string subject)
     {
         if (_deny == null)
@@ -157,6 +180,7 @@ public sealed class PermissionSet : IDisposable
         return result.PlainSubs.Length == 0 && result.QueueSubs.Length == 0;
     }
 
+    /// <summary>Disposes internal allow/deny sublists.</summary>
     public void Dispose()
     {
         _allow?.Dispose();

src/NATS.Server/Auth/IAuthenticator.cs

@@ -6,13 +6,28 @@ namespace NATS.Server.Auth;
 
 public interface IAuthenticator
 {
+    /// <summary>
+    /// Attempts to authenticate a client connection.
+    /// </summary>
+    /// <param name="context">Authentication context containing credentials and transport metadata.</param>
     AuthResult? Authenticate(ClientAuthContext context);
 }
 
 public sealed class ClientAuthContext
 {
+    /// <summary>
+    /// Gets CONNECT options and credential fields supplied by the client.
+    /// </summary>
     public required ClientOptions Opts { get; init; }
+
+    /// <summary>
+    /// Gets server-issued nonce bytes used for signature-based auth flows.
+    /// </summary>
     public required byte[] Nonce { get; init; }
+
+    /// <summary>
+    /// Gets the client TLS certificate presented during handshake, when available.
+    /// </summary>
     public X509Certificate2? ClientCertificate { get; init; }
 
     /// <summary>

src/NATS.Server/Auth/Jwt/AccountResolver.cs

@@ -17,12 +17,15 @@ public interface IAccountResolver
     /// Fetches the JWT for the given account NKey. Returns <c>null</c> when
     /// the NKey is not known to this resolver.
     /// </summary>
+    /// <param name="accountNkey">Account public NKey used as resolver lookup key.</param>
     Task<string?> FetchAsync(string accountNkey);
 
     /// <summary>
     /// Stores (or replaces) the JWT for the given account NKey. Callers that
     /// target a read-only resolver should check <see cref="IsReadOnly"/> first.
     /// </summary>
+    /// <param name="accountNkey">Account public NKey used as resolver storage key.</param>
+    /// <param name="jwt">Account JWT content associated with the key.</param>
     Task StoreAsync(string accountNkey, string jwt);
 
     /// <summary>

src/NATS.Server/Auth/Jwt/NatsJwt.cs

@@ -19,6 +19,7 @@ public static class NatsJwt
     /// <summary>
     /// Returns true if the string appears to be a JWT (starts with "eyJ").
     /// </summary>
+    /// <param name="token">Token string to inspect.</param>
     public static bool IsJwt(string token)
     {
         return !string.IsNullOrEmpty(token) && token.StartsWith(JwtPrefix, StringComparison.Ordinal);
@@ -28,6 +29,7 @@ public static class NatsJwt
     /// Decodes a JWT token into its constituent parts without verifying the signature.
     /// Returns null if the token is structurally invalid.
     /// </summary>
+    /// <param name="token">JWT string in header.payload.signature format.</param>
     public static JwtToken? Decode(string token)
     {
         if (string.IsNullOrEmpty(token))
@@ -68,6 +70,7 @@ public static class NatsJwt
     /// Decodes a JWT token and deserializes the payload as <see cref="UserClaims"/>.
     /// Returns null if the token is structurally invalid or cannot be deserialized.
     /// </summary>
+    /// <param name="token">JWT string to decode.</param>
     public static UserClaims? DecodeUserClaims(string token)
     {
         var jwt = Decode(token);
@@ -88,6 +91,7 @@ public static class NatsJwt
     /// Decodes a JWT token and deserializes the payload as <see cref="AccountClaims"/>.
     /// Returns null if the token is structurally invalid or cannot be deserialized.
     /// </summary>
+    /// <param name="token">JWT string to decode.</param>
     public static AccountClaims? DecodeAccountClaims(string token)
     {
         var jwt = Decode(token);
@@ -107,6 +111,8 @@ public static class NatsJwt
     /// <summary>
     /// Verifies the Ed25519 signature on a JWT token against the given NKey public key.
     /// </summary>
+    /// <param name="token">JWT string to verify.</param>
+    /// <param name="publicNkey">Expected signer public NKey.</param>
     public static bool Verify(string token, string publicNkey)
     {
         try
@@ -129,6 +135,9 @@ public static class NatsJwt
     /// Verifies a nonce signature against the given NKey public key.
     /// Tries base64url decoding first, then falls back to standard base64 (Go compatibility).
     /// </summary>
+    /// <param name="nonce">Raw nonce bytes originally issued by the server.</param>
+    /// <param name="signature">Signature string provided by the client.</param>
+    /// <param name="publicNkey">Client public NKey used for verification.</param>
     public static bool VerifyNonce(byte[] nonce, string signature, string publicNkey)
     {
         try
@@ -150,6 +159,7 @@ public static class NatsJwt
     /// Decodes a base64url-encoded byte array.
     /// Replaces URL-safe characters and adds padding as needed.
     /// </summary>
+    /// <param name="input">Base64url-encoded string.</param>
     internal static byte[] Base64UrlDecode(string input)
     {
         var s = input.Replace('-', '+').Replace('_', '/');
@@ -214,8 +224,10 @@ public sealed class JwtToken
 public sealed class JwtHeader
 {
     [System.Text.Json.Serialization.JsonPropertyName("alg")]
+    /// <summary>JWT signing algorithm identifier (typically <c>ed25519-nkey</c> for NATS).</summary>
     public string? Algorithm { get; set; }
 
     [System.Text.Json.Serialization.JsonPropertyName("typ")]
+    /// <summary>JWT type marker (typically <c>JWT</c>).</summary>
     public string? Type { get; set; }
 }

src/NATS.Server/Auth/NKeyUser.cs

@@ -2,11 +2,38 @@ namespace NATS.Server.Auth;
 
 public sealed class NKeyUser
 {
+    /// <summary>
+    /// Gets the public NKey used for challenge-signature authentication.
+    /// </summary>
     public required string Nkey { get; init; }
+
+    /// <summary>
+    /// Gets publish/subscribe permission rules assigned to this NKey identity.
+    /// </summary>
     public Permissions? Permissions { get; init; }
+
+    /// <summary>
+    /// Gets the account this NKey user is bound to.
+    /// </summary>
     public string? Account { get; init; }
+
+    /// <summary>
+    /// Gets an optional signing key used for delegated user JWT issuance.
+    /// </summary>
     public string? SigningKey { get; init; }
+
+    /// <summary>
+    /// Gets the issuance timestamp associated with this identity claim.
+    /// </summary>
     public DateTimeOffset? Issued { get; init; }
+
+    /// <summary>
+    /// Gets optional connection-type restrictions for this identity.
+    /// </summary>
     public IReadOnlySet<string>? AllowedConnectionTypes { get; init; }
+
+    /// <summary>
+    /// Gets a value indicating whether this identity must be presented through proxy auth.
+    /// </summary>
     public bool ProxyRequired { get; init; }
 }

src/NATS.Server/Auth/PermissionLruCache.cs

@@ -18,6 +18,10 @@ public sealed class PermissionLruCache
     private long _generation;
     private long _cacheGeneration;
 
+    /// <summary>
+    /// Creates a fixed-capacity permission LRU cache.
+    /// </summary>
+    /// <param name="capacity">Maximum number of cached permission decisions.</param>
     public PermissionLruCache(int capacity = 128)
     {
         _capacity = capacity;
@@ -51,6 +55,8 @@ public sealed class PermissionLruCache
     // ── PUB API (backward-compatible) ────────────────────────────────────────
 
     /// <summary>Looks up a PUB permission for <paramref name="key"/>.</summary>
+    /// <param name="key">Publish subject cache key.</param>
+    /// <param name="value">Cached allow/deny decision when present.</param>
     public bool TryGet(string key, out bool value)
     {
         var internalKey = "P:" + key;
@@ -71,6 +77,8 @@ public sealed class PermissionLruCache
     }
 
     /// <summary>Stores a PUB permission for <paramref name="key"/>.</summary>
+    /// <param name="key">Publish subject cache key.</param>
+    /// <param name="value">Allow/deny decision to cache.</param>
     public void Set(string key, bool value)
     {
         var internalKey = "P:" + key;
@@ -84,6 +92,8 @@ public sealed class PermissionLruCache
     // ── SUB API ───────────────────────────────────────────────────────────────
 
     /// <summary>Looks up a SUB permission for <paramref name="subject"/>.</summary>
+    /// <param name="subject">Subscribe subject cache key.</param>
+    /// <param name="value">Cached allow/deny decision when present.</param>
     public bool TryGetSub(string subject, out bool value)
     {
         var internalKey = "S:" + subject;
@@ -104,6 +114,8 @@ public sealed class PermissionLruCache
     }
 
     /// <summary>Stores a SUB permission for <paramref name="subject"/>.</summary>
+    /// <param name="subject">Subscribe subject cache key.</param>
+    /// <param name="allowed">Allow/deny decision to cache.</param>
     public void SetSub(string subject, bool allowed)
     {
         var internalKey = "S:" + subject;
@@ -116,6 +128,7 @@ public sealed class PermissionLruCache
 
     // ── Shared ────────────────────────────────────────────────────────────────
 
+    /// <summary>Current number of cached entries.</summary>
     public int Count
     {
         get

src/NATS.Server/Auth/Permissions.cs

@@ -2,19 +2,44 @@ namespace NATS.Server.Auth;
 
 public sealed class Permissions
 {
+    /// <summary>
+    /// Gets publish-side allow/deny subject rules.
+    /// </summary>
     public SubjectPermission? Publish { get; init; }
+
+    /// <summary>
+    /// Gets subscribe-side allow/deny subject rules.
+    /// </summary>
     public SubjectPermission? Subscribe { get; init; }
+
+    /// <summary>
+    /// Gets dynamic reply-publish permissions granted to request responders.
+    /// </summary>
     public ResponsePermission? Response { get; init; }
 }
 
 public sealed class SubjectPermission
 {
+    /// <summary>
+    /// Gets subject patterns explicitly permitted for the operation.
+    /// </summary>
     public IReadOnlyList<string>? Allow { get; init; }
+
+    /// <summary>
+    /// Gets subject patterns explicitly denied for the operation.
+    /// </summary>
     public IReadOnlyList<string>? Deny { get; init; }
 }
 
 public sealed class ResponsePermission
 {
+    /// <summary>
+    /// Gets the maximum number of response messages allowed on auto-generated reply subjects.
+    /// </summary>
     public int MaxMsgs { get; init; }
+
+    /// <summary>
+    /// Gets the expiration window for temporary response permissions.
+    /// </summary>
     public TimeSpan Expires { get; init; }
 }

src/NATS.Server/Auth/ResponseTracker.cs

@@ -11,17 +11,29 @@ public sealed class ResponseTracker
     private readonly Dictionary<string, (DateTime RegisteredAt, int Count)> _replies = new(StringComparer.Ordinal);
     private readonly object _lock = new();
 
+    /// <summary>
+    /// Creates a tracker for temporary response-subject permissions.
+    /// </summary>
+    /// <param name="maxMsgs">Maximum allowed publishes per reply subject (0 for unlimited).</param>
+    /// <param name="expires">TTL for each registered reply subject (<see cref="TimeSpan.Zero"/> for no TTL).</param>
     public ResponseTracker(int maxMsgs, TimeSpan expires)
     {
         _maxMsgs = maxMsgs;
         _expires = expires;
     }
 
+    /// <summary>
+    /// Gets the number of currently tracked reply subjects.
+    /// </summary>
     public int Count
     {
         get { lock (_lock) return _replies.Count; }
     }
 
+    /// <summary>
+    /// Registers a reply subject for temporary publish authorization.
+    /// </summary>
+    /// <param name="replySubject">Reply subject allowed for responder publishes.</param>
     public void RegisterReply(string replySubject)
     {
         lock (_lock)
@@ -30,6 +42,10 @@ public sealed class ResponseTracker
         }
     }
 
+    /// <summary>
+    /// Determines whether a publish to the reply subject is currently allowed.
+    /// </summary>
+    /// <param name="subject">Reply subject being authorized.</param>
     public bool IsReplyAllowed(string subject)
     {
         lock (_lock)
@@ -55,6 +71,9 @@ public sealed class ResponseTracker
         }
     }
 
+    /// <summary>
+    /// Removes expired or exhausted reply permissions from the tracker.
+    /// </summary>
     public void Prune()
     {
         lock (_lock)

src/NATS.Server/Auth/ServiceLatencyTracker.cs

@@ -11,12 +11,17 @@ public sealed class ServiceLatencyTracker
     private readonly int _maxSamples;
     private long _totalRequests;
 
+    /// <summary>
+    /// Creates a latency tracker with a bounded in-memory sample window.
+    /// </summary>
+    /// <param name="maxSamples">Maximum number of latency samples retained for percentile calculations.</param>
     public ServiceLatencyTracker(int maxSamples = 10000)
     {
         _maxSamples = maxSamples;
     }
 
     /// <summary>Records a latency sample in milliseconds.</summary>
+    /// <param name="latencyMs">Observed end-to-end service latency in milliseconds.</param>
     public void RecordLatency(double latencyMs)
     {
         lock (_lock)
@@ -28,11 +33,15 @@ public sealed class ServiceLatencyTracker
         }
     }
 
+    /// <summary>Returns the 50th percentile (median) latency in milliseconds.</summary>
     public double GetP50() => GetPercentile(0.50);
+    /// <summary>Returns the 90th percentile latency in milliseconds.</summary>
     public double GetP90() => GetPercentile(0.90);
+    /// <summary>Returns the 99th percentile latency in milliseconds.</summary>
     public double GetP99() => GetPercentile(0.99);
 
     /// <summary>Returns the value at the given percentile (0.0–1.0) over recorded samples.</summary>
+    /// <param name="percentile">Percentile fraction between 0.0 and 1.0.</param>
     public double GetPercentile(double percentile)
     {
         lock (_lock)
@@ -61,16 +70,19 @@ public sealed class ServiceLatencyTracker
         return sum / samples.Count;
     }
 
+    /// <summary>Total number of latency observations recorded.</summary>
     public long TotalRequests
     {
         get { lock (_lock) return _totalRequests; }
     }
 
+    /// <summary>Arithmetic mean latency across currently retained samples.</summary>
     public double AverageLatencyMs
     {
         get { lock (_lock) return ComputeAverage(_samples); }
     }
 
+    /// <summary>Minimum latency among currently retained samples.</summary>
     public double MinLatencyMs
     {
         get
@@ -80,6 +92,7 @@ public sealed class ServiceLatencyTracker
         }
     }
 
+    /// <summary>Maximum latency among currently retained samples.</summary>
     public double MaxLatencyMs
     {
         get
@@ -89,6 +102,7 @@ public sealed class ServiceLatencyTracker
         }
     }
 
+    /// <summary>Number of samples currently retained in memory.</summary>
     public int SampleCount
     {
         get { lock (_lock) return _samples.Count; }

src/NATS.Server/Auth/TlsMapAuthenticator.cs

@@ -11,6 +11,10 @@ public sealed class TlsMapAuthenticator : IAuthenticator
     private readonly Dictionary<string, User> _usersByDn;
     private readonly Dictionary<string, User> _usersByCn;
 
+    /// <summary>
+    /// Creates a TLS-map authenticator using configured users keyed by DN/CN-style identities.
+    /// </summary>
+    /// <param name="users">Configured users used for DN/CN lookup matches.</param>
     public TlsMapAuthenticator(IReadOnlyList<User> users)
     {
         _usersByDn = new Dictionary<string, User>(StringComparer.OrdinalIgnoreCase);
@@ -22,6 +26,10 @@ public sealed class TlsMapAuthenticator : IAuthenticator
         }
     }
 
+    /// <summary>
+    /// Authenticates a client by matching certificate subject/SAN data to configured users.
+    /// </summary>
+    /// <param name="context">Authentication context containing the client TLS certificate.</param>
     public AuthResult? Authenticate(ClientAuthContext context)
     {
         var cert = context.ClientCertificate;
@@ -65,6 +73,10 @@ public sealed class TlsMapAuthenticator : IAuthenticator
         return null;
     }
 
+    /// <summary>
+    /// Extracts domain-component RDN elements from a distinguished name.
+    /// </summary>
+    /// <param name="dn">Distinguished name to inspect for <c>DC=</c> elements.</param>
     internal static string GetTlsAuthDcs(X500DistinguishedName dn)
     {
         if (string.IsNullOrWhiteSpace(dn.Name))
@@ -82,6 +94,10 @@ public sealed class TlsMapAuthenticator : IAuthenticator
         return string.Join(",", dcs);
     }
 
+    /// <summary>
+    /// Splits a DNS alternative-name value into normalized lowercase labels.
+    /// </summary>
+    /// <param name="dnsAltName">DNS SAN value from a certificate.</param>
     internal static string[] DnsAltNameLabels(string dnsAltName)
     {
         if (string.IsNullOrWhiteSpace(dnsAltName))
@@ -90,6 +106,11 @@ public sealed class TlsMapAuthenticator : IAuthenticator
         return dnsAltName.ToLowerInvariant().Split('.', StringSplitOptions.RemoveEmptyEntries);
     }
 
+    /// <summary>
+    /// Determines whether SAN DNS labels match any URL host in the provided list.
+    /// </summary>
+    /// <param name="dnsAltNameLabels">Normalized SAN label sequence (supports wildcard first label).</param>
+    /// <param name="urls">Candidate URLs whose hosts are compared against SAN labels.</param>
     internal static bool DnsAltNameMatches(string[] dnsAltNameLabels, IReadOnlyList<Uri?> urls)
     {
         foreach (var url in urls)

src/NATS.Server/Auth/User.cs

@@ -2,11 +2,38 @@ namespace NATS.Server.Auth;
 
 public sealed class User
 {
+    /// <summary>
+    /// Gets the username used for CONNECT credential authentication.
+    /// </summary>
     public required string Username { get; init; }
+
+    /// <summary>
+    /// Gets the password associated with <see cref="Username"/>.
+    /// </summary>
     public required string Password { get; init; }
+
+    /// <summary>
+    /// Gets publish/subscribe permission rules assigned to this user.
+    /// </summary>
     public Permissions? Permissions { get; init; }
+
+    /// <summary>
+    /// Gets the account this user is bound to for subject and subscription isolation.
+    /// </summary>
     public string? Account { get; init; }
+
+    /// <summary>
+    /// Gets an optional cutoff timestamp after which new connections are rejected.
+    /// </summary>
     public DateTimeOffset? ConnectionDeadline { get; init; }
+
+    /// <summary>
+    /// Gets optional connection-type restrictions (client, route, gateway, leaf, and so on).
+    /// </summary>
     public IReadOnlySet<string>? AllowedConnectionTypes { get; init; }
+
+    /// <summary>
+    /// Gets a value indicating whether this identity must authenticate through trusted proxy headers.
+    /// </summary>
     public bool ProxyRequired { get; init; }
 }

src/NATS.Server/ClientFlags.cs

@@ -25,16 +25,28 @@ public sealed class ClientFlagHolder
 {
     private int _flags;
 
+    /// <summary>
+    /// Atomically sets the specified client state flag.
+    /// </summary>
+    /// <param name="flag">Flag to set.</param>
     public void SetFlag(ClientFlags flag)
     {
         Interlocked.Or(ref _flags, (int)flag);
     }
 
+    /// <summary>
+    /// Atomically clears the specified client state flag.
+    /// </summary>
+    /// <param name="flag">Flag to clear.</param>
     public void ClearFlag(ClientFlags flag)
     {
         Interlocked.And(ref _flags, ~(int)flag);
     }
 
+    /// <summary>
+    /// Checks whether the specified client state flag is currently set.
+    /// </summary>
+    /// <param name="flag">Flag to test.</param>
     public bool HasFlag(ClientFlags flag)
     {
         return (Volatile.Read(ref _flags) & (int)flag) != 0;

src/NATS.Server/ClientTraceInfo.cs

@@ -29,6 +29,9 @@ public sealed class ClientTraceInfo
     /// Records a message delivery trace if tracing is enabled.
     /// Go reference: server/client.go — traceMsg / TraceMsgDelivery.
     /// </summary>
+    /// <param name="subject">Published subject that triggered this delivery path.</param>
+    /// <param name="destination">Destination descriptor such as a client, queue group, or route hop.</param>
+    /// <param name="payloadSize">Payload size in bytes used for throughput and fan-out diagnostics.</param>
     public void TraceMsgDelivery(string subject, string destination, int payloadSize)
     {
         if (!TraceEnabled) return;
@@ -50,6 +53,8 @@ public sealed class ClientTraceInfo
     /// subscriptions on the same client.
     /// Go reference: server/client.go — c.echo check in deliverMsg.
     /// </summary>
+    /// <param name="publisherClientId">Client identifier that originated the publish.</param>
+    /// <param name="subscriberClientId">Client identifier for the subscription currently being evaluated.</param>
     public bool ShouldEcho(string publisherClientId, string subscriberClientId)
     {
         if (EchoEnabled) return true;
@@ -76,8 +81,23 @@ public sealed class ClientTraceInfo
 
 public sealed record TraceRecord
 {
+    /// <summary>
+    /// Gets the routed subject for the traced delivery event.
+    /// </summary>
     public string Subject { get; init; } = string.Empty;
+
+    /// <summary>
+    /// Gets the resolved destination where the server sent the message.
+    /// </summary>
     public string Destination { get; init; } = string.Empty;
+
+    /// <summary>
+    /// Gets the payload size in bytes for the traced message.
+    /// </summary>
     public int PayloadSize { get; init; }
+
+    /// <summary>
+    /// Gets the UTC timestamp captured when the trace event was recorded.
+    /// </summary>
     public DateTime TimestampUtc { get; init; }
 }

src/NATS.Server/Configuration/ClusterOptions.cs

@@ -1,15 +1,48 @@
 namespace NATS.Server.Configuration;
 
+/// <summary>
+/// Cluster listener and route fan-out settings used for server-to-server mesh links.
+/// </summary>
 public sealed class ClusterOptions
 {
+    /// <summary>
+    /// Gets or sets the local cluster name advertised during route handshakes.
+    /// </summary>
     public string? Name { get; set; }
+
+    /// <summary>
+    /// Gets or sets the network interface used to accept inbound route connections.
+    /// </summary>
     public string Host { get; set; } = "0.0.0.0";
+
+    /// <summary>
+    /// Gets or sets the TCP port for the cluster route listener.
+    /// </summary>
     public int Port { get; set; } = 6222;
+
+    /// <summary>
+    /// Gets or sets the number of parallel route connections maintained per remote server.
+    /// </summary>
     public int PoolSize { get; set; } = 3;
+
+    /// <summary>
+    /// Gets or sets the configured outbound route URLs used to join peer servers.
+    /// </summary>
     public List<string> Routes { get; set; } = [];
+
+    /// <summary>
+    /// Gets or sets account names that should use dedicated route handling.
+    /// </summary>
     public List<string> Accounts { get; set; } = [];
+
+    /// <summary>
+    /// Gets or sets compression behavior for inter-server route traffic.
+    /// </summary>
     public RouteCompression Compression { get; set; } = RouteCompression.None;
 
     // Go: opts.go — cluster write_deadline
+    /// <summary>
+    /// Gets or sets the write deadline enforced for route protocol socket operations.
+    /// </summary>
     public TimeSpan WriteDeadline { get; set; }
 }

src/NATS.Server/Configuration/ConfigProcessor.cs

@@ -19,6 +19,7 @@ public static class ConfigProcessor
     /// <summary>
     /// Parses a configuration file and returns the populated options.
     /// </summary>
+    /// <param name="filePath">Absolute or relative path to the NATS configuration file to load.</param>
     public static NatsOptions ProcessConfigFile(string filePath)
     {
         var config = NatsConfParser.ParseFile(filePath);
@@ -30,6 +31,7 @@ public static class ConfigProcessor
     /// <summary>
     /// Parses configuration text (not from a file) and returns the populated options.
     /// </summary>
+    /// <param name="configText">Raw configuration text in NATS server config format.</param>
     public static NatsOptions ProcessConfig(string configText)
     {
         var config = NatsConfParser.Parse(configText);
@@ -42,6 +44,8 @@ public static class ConfigProcessor
     /// Applies a parsed configuration dictionary to existing options.
     /// Throws <see cref="ConfigProcessorException"/> if any validation errors are collected.
     /// </summary>
+    /// <param name="config">Parsed config tree keyed by top-level field names.</param>
+    /// <param name="opts">Options instance that receives normalized values from the parsed config.</param>
     public static void ApplyConfig(Dictionary<string, object?> config, NatsOptions opts)
     {
         var errors = new List<string>();
@@ -423,6 +427,7 @@ public static class ConfigProcessor
     ///   <item>A number (long/double) treated as seconds</item>
     /// </list>
     /// </summary>
+    /// <param name="value">Raw duration token from configuration (string or numeric seconds).</param>
     internal static TimeSpan ParseDuration(object? value)
     {
         return value switch
@@ -1877,7 +1882,14 @@ public static class ConfigProcessor
 public sealed class ConfigProcessorException(string message, List<string> errors, List<string>? warnings = null)
     : Exception(message)
 {
+    /// <summary>
+    /// Gets the list of blocking configuration errors that prevented startup.
+    /// </summary>
     public IReadOnlyList<string> Errors => errors;
+
+    /// <summary>
+    /// Gets non-fatal configuration warnings collected during processing.
+    /// </summary>
     public IReadOnlyList<string> Warnings => warnings ?? [];
 }
 
@@ -1887,6 +1899,9 @@ public sealed class ConfigProcessorException(string message, List<string> errors
 /// </summary>
 public class ConfigWarningException(string message, string? source = null) : Exception(message)
 {
+    /// <summary>
+    /// Gets the location within the source config where this warning originated, when available.
+    /// </summary>
     public string? SourceLocation { get; } = source;
 }
 
@@ -1897,5 +1912,8 @@ public class ConfigWarningException(string message, string? source = null) : Exc
 public sealed class UnknownConfigFieldWarning(string field, string? source = null)
     : ConfigWarningException($"unknown field {field}", source)
 {
+    /// <summary>
+    /// Gets the unknown top-level or nested field name encountered in the configuration file.
+    /// </summary>
     public string Field { get; } = field;
 }

src/NATS.Server/Configuration/ConfigReloader.cs

@@ -810,6 +810,11 @@ public sealed class ConfigReloadResult
     /// <summary>
     /// Initializes a config reload result payload.
     /// </summary>
+    /// <param name="Unchanged">Whether reload was skipped because the config digest was unchanged.</param>
+    /// <param name="NewOptions">Newly parsed options candidate for applying a reload.</param>
+    /// <param name="NewDigest">Digest string of the candidate config content.</param>
+    /// <param name="Changes">Detected option differences for this reload attempt.</param>
+    /// <param name="Errors">Validation errors that block applying the reload.</param>
     public ConfigReloadResult(
         bool Unchanged,
         NatsOptions? NewOptions = null,

src/NATS.Server/Configuration/IConfigChange.cs

@@ -46,9 +46,28 @@ public sealed class ConfigChange(
     bool isTlsChange = false,
     bool isNonReloadable = false) : IConfigChange
 {
+    /// <summary>
+    /// Gets the changed option name.
+    /// </summary>
     public string Name => name;
+
+    /// <summary>
+    /// Gets a value indicating whether this change affects logging configuration.
+    /// </summary>
     public bool IsLoggingChange => isLoggingChange;
+
+    /// <summary>
+    /// Gets a value indicating whether this change affects authentication configuration.
+    /// </summary>
     public bool IsAuthChange => isAuthChange;
+
+    /// <summary>
+    /// Gets a value indicating whether this change affects TLS configuration.
+    /// </summary>
     public bool IsTlsChange => isTlsChange;
+
+    /// <summary>
+    /// Gets a value indicating whether this change cannot be applied without restart.
+    /// </summary>
     public bool IsNonReloadable => isNonReloadable;
 }

src/NATS.Server/Configuration/NatsConfParser.cs

@@ -28,6 +28,7 @@ public static class NatsConfParser
     /// <summary>
     /// Parses a NATS configuration string into a dictionary.
     /// </summary>
+    /// <param name="data">Raw configuration text.</param>
     public static Dictionary<string, object?> Parse(string data)
     {
         var tokens = NatsConfLexer.Tokenize(data);
@@ -40,11 +41,13 @@ public static class NatsConfParser
     /// Pedantic compatibility API (Go: ParseWithChecks).
     /// Uses the same parser behavior as <see cref="Parse(string)"/>.
     /// </summary>
+    /// <param name="data">Raw configuration text.</param>
     public static Dictionary<string, object?> ParseWithChecks(string data) => Parse(data);
 
     /// <summary>
     /// Parses a NATS configuration file into a dictionary.
     /// </summary>
+    /// <param name="filePath">Path to the configuration file.</param>
     public static Dictionary<string, object?> ParseFile(string filePath) =>
         ParseFile(filePath, includeDepth: 0);
 
@@ -52,6 +55,7 @@ public static class NatsConfParser
     /// Pedantic compatibility API (Go: ParseFileWithChecks).
     /// Uses the same parser behavior as <see cref="ParseFile(string)"/>.
     /// </summary>
+    /// <param name="filePath">Path to the configuration file.</param>
     public static Dictionary<string, object?> ParseFileWithChecks(string filePath) => ParseFile(filePath);
 
     private static Dictionary<string, object?> ParseFile(string filePath, int includeDepth)
@@ -68,6 +72,7 @@ public static class NatsConfParser
     /// Parses a NATS configuration file and returns the parsed config plus a
     /// SHA-256 digest of the raw file content formatted as "sha256:&lt;hex&gt;".
     /// </summary>
+    /// <param name="filePath">Path to the configuration file.</param>
     public static (Dictionary<string, object?> Config, string Digest) ParseFileWithDigest(string filePath)
     {
         var rawBytes = File.ReadAllBytes(filePath);
@@ -85,6 +90,7 @@ public static class NatsConfParser
     /// <summary>
     /// Pedantic compatibility API (Go: ParseFileWithChecksDigest).
     /// </summary>
+    /// <param name="filePath">Path to the configuration file.</param>
     public static (Dictionary<string, object?> Config, string Digest) ParseFileWithChecksDigest(string filePath)
     {
         var data = File.ReadAllText(filePath);
@@ -204,13 +210,26 @@ public static class NatsConfParser
         // Pedantic-mode key token stack (Go parser field: ikeys).
         private readonly List<Token> _itemKeys = new(4);
 
+        /// <summary>Root parsed mapping for the current parser execution.</summary>
         public Dictionary<string, object?> Mapping { get; } = new(StringComparer.OrdinalIgnoreCase);
 
+        /// <summary>
+        /// Creates parser state for tokenized config input.
+        /// </summary>
+        /// <param name="tokens">Token stream from the config lexer.</param>
+        /// <param name="baseDir">Base directory used to resolve include paths.</param>
         public ParserState(IReadOnlyList<Token> tokens, string baseDir)
             : this(tokens, baseDir, [], includeDepth: 0)
         {
         }
 
+        /// <summary>
+        /// Creates parser state with explicit env-reference tracking and include depth.
+        /// </summary>
+        /// <param name="tokens">Token stream from the config lexer.</param>
+        /// <param name="baseDir">Base directory used to resolve include paths.</param>
+        /// <param name="envVarReferences">Shared environment-variable recursion guard set.</param>
+        /// <param name="includeDepth">Current include nesting depth.</param>
         public ParserState(IReadOnlyList<Token> tokens, string baseDir, HashSet<string> envVarReferences, int includeDepth)
         {
             _tokens = tokens;
@@ -219,6 +238,9 @@ public static class NatsConfParser
             _includeDepth = includeDepth;
         }
 
+        /// <summary>
+        /// Executes the parse loop and builds <see cref="Mapping"/>.
+        /// </summary>
         public void Run()
         {
             PushContext(Mapping);

src/NATS.Server/Configuration/NatsConfToken.cs

@@ -36,6 +36,13 @@ public sealed class PedanticToken
     private readonly bool _usedVariable;
     private readonly string _sourceFile;
 
+    /// <summary>
+    /// Creates a parser token wrapper that preserves resolved value and source metadata.
+    /// </summary>
+    /// <param name="item">Raw lexer token captured from the configuration source.</param>
+    /// <param name="value">Optional parsed value override when token text has been normalized.</param>
+    /// <param name="usedVariable">Indicates whether this token originated from variable substitution.</param>
+    /// <param name="sourceFile">Source file path associated with this token, when available.</param>
     public PedanticToken(Token item, object? value = null, bool usedVariable = false, string sourceFile = "")
     {
         _item = item;
@@ -44,15 +51,33 @@ public sealed class PedanticToken
         _sourceFile = sourceFile ?? string.Empty;
     }
 
+    /// <summary>
+    /// Serializes the token value into JSON, matching Go parser diagnostics formatting.
+    /// </summary>
     public string MarshalJson() => JsonSerializer.Serialize(Value());
 
+    /// <summary>
+    /// Returns the resolved token value, or raw token text when no typed value is stored.
+    /// </summary>
     public object? Value() => _value ?? _item.Value;
 
+    /// <summary>
+    /// Returns the 1-based source line where the token was parsed.
+    /// </summary>
     public int Line() => _item.Line;
 
+    /// <summary>
+    /// Returns whether variable interpolation contributed to this token.
+    /// </summary>
     public bool IsUsedVariable() => _usedVariable;
 
+    /// <summary>
+    /// Returns the source file path associated with this token.
+    /// </summary>
     public string SourceFile() => _sourceFile;
 
+    /// <summary>
+    /// Returns the 1-based character position of the token on its source line.
+    /// </summary>
     public int Position() => _item.Position;
 }

src/NATS.Server/Events/EventCompressor.cs

@@ -77,6 +77,8 @@ public static class EventCompressor
     /// <summary>
     /// Compresses <paramref name="payload"/> using the requested <paramref name="compression"/>.
     /// </summary>
+    /// <param name="payload">Uncompressed event payload bytes.</param>
+    /// <param name="compression">Compression algorithm to apply for transport.</param>
     public static byte[] Compress(ReadOnlySpan<byte> payload, EventCompressionType compression)
     {
         if (payload.IsEmpty)
@@ -104,6 +106,8 @@ public static class EventCompressor
     /// <summary>
     /// Decompresses <paramref name="compressed"/> using the selected <paramref name="compression"/>.
     /// </summary>
+    /// <param name="compressed">Compressed event payload bytes.</param>
+    /// <param name="compression">Encoding that was used when the payload was produced.</param>
     public static byte[] Decompress(ReadOnlySpan<byte> compressed, EventCompressionType compression)
     {
         if (compressed.IsEmpty)
@@ -150,6 +154,9 @@ public static class EventCompressor
     /// <summary>
     /// Compresses using <paramref name="compression"/> when payload size exceeds threshold.
     /// </summary>
+    /// <param name="payload">Raw event payload that may be compressed.</param>
+    /// <param name="compression">Preferred compression algorithm for eligible payloads.</param>
+    /// <param name="thresholdBytes">Minimum payload size required before compression is attempted.</param>
     public static (byte[] Data, bool Compressed) CompressIfBeneficial(
         ReadOnlySpan<byte> payload,
         EventCompressionType compression,
@@ -189,6 +196,7 @@ public static class EventCompressor
     /// Parses an HTTP Accept-Encoding value into a supported compression type.
     /// Go reference: events.go getAcceptEncoding().
     /// </summary>
+    /// <param name="acceptEncoding">Raw HTTP <c>Accept-Encoding</c> header value from the client.</param>
     public static EventCompressionType GetAcceptEncoding(string? acceptEncoding)
     {
         if (string.IsNullOrWhiteSpace(acceptEncoding))

src/NATS.Server/Events/EventSubjects.cs

@@ -74,6 +74,13 @@ public static class EventSubjects
 /// Callback signature for system message handlers.
 /// Maps to Go's sysMsgHandler type in events.go:109.
 /// </summary>
+/// <param name="sub">Subscription metadata that matched the incoming system message.</param>
+/// <param name="client">Client connection context that delivered the message, when available.</param>
+/// <param name="account">Owning account context for account-scoped system events.</param>
+/// <param name="subject">System subject that triggered this callback.</param>
+/// <param name="reply">Reply inbox subject for request/reply system handlers.</param>
+/// <param name="headers">Optional message headers encoded by the publisher.</param>
+/// <param name="message">Raw system advisory or request payload bytes.</param>
 public delegate void SystemMessageHandler(
     Subscription? sub,
     INatsClient? client,

src/NATS.Server/Gateways/GatewayCommands.cs

@@ -45,6 +45,8 @@ public static class GatewayCommands
     /// Wire format: GS+ {account} {subject}\r\n
     /// Go reference: gateway.go — sendGatewaySubsToGateway, RS+ propagation.
     /// </summary>
+    /// <param name="account">Origin account used for gateway interest tracking.</param>
+    /// <param name="subject">Subject pattern being subscribed across clusters.</param>
     public static byte[] FormatSub(string account, string subject)
         => Encoding.UTF8.GetBytes($"GS+ {account} {subject}\r\n");
 
@@ -53,6 +55,8 @@ public static class GatewayCommands
     /// Wire format: GS- {account} {subject}\r\n
     /// Go reference: gateway.go — sendGatewayUnsubToGateway, RS- propagation.
     /// </summary>
+    /// <param name="account">Origin account used for gateway interest tracking.</param>
+    /// <param name="subject">Subject pattern being removed from remote interest state.</param>
     public static byte[] FormatUnsub(string account, string subject)
         => Encoding.UTF8.GetBytes($"GS- {account} {subject}\r\n");
 
@@ -62,6 +66,8 @@ public static class GatewayCommands
     /// Mode: "O" for Optimistic (send everything), "I" for Interest-only.
     /// Go reference: gateway.go — switchAccountToInterestMode, GMODE command.
     /// </summary>
+    /// <param name="account">Account whose cross-cluster routing mode is being updated.</param>
+    /// <param name="mode">Target gateway interest mode for that account.</param>
     public static byte[] FormatMode(string account, GatewayInterestMode mode)
     {
         var modeStr = mode == GatewayInterestMode.InterestOnly ? "I" : "O";
@@ -73,6 +79,7 @@ public static class GatewayCommands
     /// Returns null if the command prefix is unrecognized.
     /// Go reference: gateway.go — processGatewayMsg command dispatch.
     /// </summary>
+    /// <param name="line">Raw protocol line prefix read from a gateway connection.</param>
     public static GatewayCommandType? ParseCommandType(ReadOnlySpan<byte> line)
     {
         if (line.StartsWith(InfoPrefix)) return GatewayCommandType.Info;

src/NATS.Server/Gateways/GatewayInterestTracker.cs

@@ -42,6 +42,10 @@ public sealed class GatewayInterestTracker
     // Per-account state: mode + no-interest set (Optimistic) or positive interest set (InterestOnly)
     private readonly ConcurrentDictionary<string, AccountState> _accounts = new(StringComparer.Ordinal);
 
+    /// <summary>
+    /// Creates a gateway interest tracker with a configurable mode-switch threshold.
+    /// </summary>
+    /// <param name="noInterestThreshold">No-interest entry count that triggers InterestOnly mode.</param>
     public GatewayInterestTracker(int noInterestThreshold = DefaultNoInterestThreshold)
     {
         _noInterestThreshold = noInterestThreshold;
@@ -51,6 +55,7 @@ public sealed class GatewayInterestTracker
     /// Returns the current interest mode for the given account.
     /// Accounts default to Optimistic until the no-interest threshold is exceeded.
     /// </summary>
+    /// <param name="account">Account name/identifier.</param>
     public GatewayInterestMode GetMode(string account)
         => _accounts.TryGetValue(account, out var state) ? state.Mode : GatewayInterestMode.Optimistic;
 
@@ -58,6 +63,8 @@ public sealed class GatewayInterestTracker
     /// Track a positive interest (RS+ received from remote) for an account/subject.
     /// Go: gateway.go:1540 (processGatewayAccountSub — adds to interest set)
     /// </summary>
+    /// <param name="account">Account name/identifier.</param>
+    /// <param name="subject">Subject or pattern with positive remote interest.</param>
     public void TrackInterest(string account, string subject)
     {
         var state = GetOrCreateState(account);
@@ -83,6 +90,8 @@ public sealed class GatewayInterestTracker
     /// When the no-interest set crosses the threshold, switches to InterestOnly mode.
     /// Go: gateway.go:1560 (processGatewayAccountUnsub — tracks no-interest, triggers switch)
     /// </summary>
+    /// <param name="account">Account name/identifier.</param>
+    /// <param name="subject">Subject or pattern that should be treated as no-interest.</param>
     public void TrackNoInterest(string account, string subject)
     {
         var state = GetOrCreateState(account);
@@ -110,6 +119,8 @@ public sealed class GatewayInterestTracker
     /// for the given account and subject.
     /// Go: gateway.go:2900 (shouldForwardMsg — checks mode and interest)
     /// </summary>
+    /// <param name="account">Account name/identifier.</param>
+    /// <param name="subject">Subject being considered for forwarding.</param>
     public bool ShouldForward(string account, string subject)
     {
         if (!_accounts.TryGetValue(account, out var state))
@@ -141,6 +152,7 @@ public sealed class GatewayInterestTracker
     /// Called when the remote signals it is in interest-only mode.
     /// Go: gateway.go:1500 (switchToInterestOnlyMode)
     /// </summary>
+    /// <param name="account">Account name/identifier.</param>
     public void SwitchToInterestOnly(string account)
     {
         var state = GetOrCreateState(account);
@@ -179,6 +191,7 @@ public sealed class GatewayInterestTracker
     /// <summary>Per-account mutable state. All access must be under the instance lock.</summary>
     private sealed class AccountState
     {
+        /// <summary>Current forwarding mode for this account.</summary>
         public GatewayInterestMode Mode { get; set; } = GatewayInterestMode.Optimistic;
 
         /// <summary>Subjects with no remote interest (used in Optimistic mode).</summary>

src/NATS.Server/INatsClient.cs

@@ -5,18 +5,45 @@ namespace NATS.Server;
 
 public interface INatsClient
 {
+    /// <summary>Unique server-assigned client identifier.</summary>
     ulong Id { get; }
+    /// <summary>Client kind (client, route, gateway, leaf, system, etc.).</summary>
     ClientKind Kind { get; }
+    /// <summary>Whether this client is server-internal and not socket-backed.</summary>
     bool IsInternal => Kind.IsInternal();
+    /// <summary>Account context associated with this client.</summary>
     Account? Account { get; }
+    /// <summary>Parsed CONNECT options for this client when available.</summary>
     ClientOptions? ClientOpts { get; }
+    /// <summary>Resolved publish/subscribe permissions for this client.</summary>
     ClientPermissions? Permissions { get; }
 
+    /// <summary>
+    /// Sends a protocol message to a subscription with immediate flush semantics.
+    /// </summary>
+    /// <param name="subject">Delivery subject sent to the client.</param>
+    /// <param name="sid">Subscription identifier receiving the message.</param>
+    /// <param name="replyTo">Optional reply subject for request-reply flows.</param>
+    /// <param name="headers">Serialized NATS headers payload.</param>
+    /// <param name="payload">Message payload bytes.</param>
     void SendMessage(string subject, string sid, string? replyTo,
         ReadOnlyMemory<byte> headers, ReadOnlyMemory<byte> payload);
+    /// <summary>
+    /// Sends a protocol message without forcing an immediate flush.
+    /// </summary>
+    /// <param name="subject">Delivery subject sent to the client.</param>
+    /// <param name="sid">Subscription identifier receiving the message.</param>
+    /// <param name="replyTo">Optional reply subject for request-reply flows.</param>
+    /// <param name="headers">Serialized NATS headers payload.</param>
+    /// <param name="payload">Message payload bytes.</param>
     void SendMessageNoFlush(string subject, string sid, string? replyTo,
         ReadOnlyMemory<byte> headers, ReadOnlyMemory<byte> payload);
+    /// <summary>Signals that queued outbound bytes should be flushed.</summary>
     void SignalFlush();
+    /// <summary>Queues outbound protocol bytes for asynchronous write-loop transmission.</summary>
+    /// <param name="data">Serialized protocol bytes to queue.</param>
     bool QueueOutbound(ReadOnlyMemory<byte> data);
+    /// <summary>Removes a subscription by subscription identifier.</summary>
+    /// <param name="sid">Subscription identifier to remove.</param>
     void RemoveSubscription(string sid);
 }

src/NATS.Server/IO/OutboundBufferPool.cs

@@ -23,8 +23,11 @@ public sealed class OutboundBufferPool
     private long _returnCount;
     private long _broadcastCount;
 
+    /// <summary>Total buffer rent operations served by the pool.</summary>
     public long RentCount      => Interlocked.Read(ref _rentCount);
+    /// <summary>Total buffer return operations accepted by the pool.</summary>
     public long ReturnCount    => Interlocked.Read(ref _returnCount);
+    /// <summary>Total broadcast-drain operations performed.</summary>
     public long BroadcastCount => Interlocked.Read(ref _broadcastCount);
 
     // -----------------------------------------------------------------------
@@ -36,6 +39,7 @@ public sealed class OutboundBufferPool
     /// <paramref name="size"/> bytes. Tries the internal pool first; falls back to
     /// <see cref="MemoryPool{T}.Shared"/>.
     /// </summary>
+    /// <param name="size">Minimum required buffer size.</param>
     public IMemoryOwner<byte> Rent(int size)
     {
         Interlocked.Increment(ref _rentCount);
@@ -70,6 +74,7 @@ public sealed class OutboundBufferPool
     /// <paramref name="size"/> bytes. The caller is responsible for calling
     /// <see cref="ReturnBuffer"/> when finished.
     /// </summary>
+    /// <param name="size">Minimum required buffer size.</param>
     public byte[] RentBuffer(int size)
     {
         Interlocked.Increment(ref _rentCount);
@@ -94,6 +99,7 @@ public sealed class OutboundBufferPool
     /// Returns <paramref name="buffer"/> to the appropriate tier so it can be
     /// reused by a subsequent <see cref="RentBuffer"/> call.
     /// </summary>
+    /// <param name="buffer">Buffer previously rented from this pool.</param>
     public void ReturnBuffer(byte[] buffer)
     {
         Interlocked.Increment(ref _returnCount);
@@ -128,6 +134,8 @@ public sealed class OutboundBufferPool
     ///
     /// Go reference: client.go — broadcast flush coalescing for fan-out.
     /// </summary>
+    /// <param name="pendingWrites">Pending write segments to coalesce.</param>
+    /// <param name="destination">Destination buffer receiving the concatenated payloads.</param>
     public int BroadcastDrain(IReadOnlyList<ReadOnlyMemory<byte>> pendingWrites, byte[] destination)
     {
         var offset = 0;
@@ -144,6 +152,7 @@ public sealed class OutboundBufferPool
     /// Returns the total number of bytes needed to coalesce all
     /// <paramref name="pendingWrites"/> into a single buffer.
     /// </summary>
+    /// <param name="pendingWrites">Pending write segments to size.</param>
     public static int CalculateBroadcastSize(IReadOnlyList<ReadOnlyMemory<byte>> pendingWrites)
     {
         var total = 0;
@@ -164,15 +173,22 @@ public sealed class OutboundBufferPool
         private readonly ConcurrentBag<byte[]> _pool;
         private byte[]? _buffer;
 
+        /// <summary>
+        /// Creates a pooled memory owner backed by a reusable byte array.
+        /// </summary>
+        /// <param name="buffer">Rented backing buffer.</param>
+        /// <param name="pool">Pool to return the buffer to on disposal.</param>
         public PooledMemoryOwner(byte[] buffer, ConcurrentBag<byte[]> pool)
         {
             _buffer = buffer;
             _pool   = pool;
         }
 
+        /// <summary>Memory view over the currently owned buffer.</summary>
         public Memory<byte> Memory =>
             _buffer is { } b ? b.AsMemory() : Memory<byte>.Empty;
 
+        /// <summary>Returns the owned buffer to the originating pool.</summary>
         public void Dispose()
         {
             if (Interlocked.Exchange(ref _buffer, null) is { } b)

src/NATS.Server/Imports/ExportAuth.cs

@@ -4,11 +4,30 @@ namespace NATS.Server.Imports;
 
 public sealed class ExportAuth
 {
+    /// <summary>
+    /// Gets a value indicating whether importers must present a token for access.
+    /// </summary>
     public bool TokenRequired { get; init; }
+
+    /// <summary>
+    /// Gets the account-token subject position used for legacy tokenized export patterns.
+    /// </summary>
     public uint AccountPosition { get; init; }
+
+    /// <summary>
+    /// Gets explicit account names permitted to import this export.
+    /// </summary>
     public HashSet<string>? ApprovedAccounts { get; init; }
+
+    /// <summary>
+    /// Gets accounts revoked from import access, mapped to revocation timestamps.
+    /// </summary>
     public Dictionary<string, long>? RevokedAccounts { get; init; }
 
+    /// <summary>
+    /// Determines whether the specified account is currently authorized for this export.
+    /// </summary>
+    /// <param name="account">Importing account requesting access.</param>
     public bool IsAuthorized(Account account)
     {
         if (RevokedAccounts != null && RevokedAccounts.ContainsKey(account.Name))

src/NATS.Server/Imports/ExportMap.cs

@@ -2,7 +2,18 @@ namespace NATS.Server.Imports;
 
 public sealed class ExportMap
 {
+    /// <summary>
+    /// Gets stream exports keyed by exported subject.
+    /// </summary>
     public Dictionary<string, StreamExport> Streams { get; } = new(StringComparer.Ordinal);
+
+    /// <summary>
+    /// Gets service exports keyed by exported subject.
+    /// </summary>
     public Dictionary<string, ServiceExport> Services { get; } = new(StringComparer.Ordinal);
+
+    /// <summary>
+    /// Gets temporary response imports keyed by generated reply prefix.
+    /// </summary>
     public Dictionary<string, ServiceImport> Responses { get; } = new(StringComparer.Ordinal);
 }

src/NATS.Server/Imports/ImportMap.cs

@@ -4,9 +4,20 @@ namespace NATS.Server.Imports;
 
 public sealed class ImportMap
 {
+    /// <summary>
+    /// Gets stream import definitions configured for the account.
+    /// </summary>
     public List<StreamImport> Streams { get; } = [];
+
+    /// <summary>
+    /// Gets service import definitions grouped by source subject.
+    /// </summary>
     public Dictionary<string, List<ServiceImport>> Services { get; } = new(StringComparer.Ordinal);
 
+    /// <summary>
+    /// Adds a service import under its source subject key.
+    /// </summary>
+    /// <param name="si">Service import definition to add.</param>
     public void AddServiceImport(ServiceImport si)
     {
         if (!Services.TryGetValue(si.From, out var list))

src/NATS.Server/Imports/LatencyTracker.cs

@@ -2,29 +2,57 @@ using System.Text.Json.Serialization;
 
 namespace NATS.Server.Imports;
 
+/// <summary>
+/// Serialized payload published for exported-service latency advisories.
+/// </summary>
 public sealed class ServiceLatencyMsg
 {
+    /// <summary>
+    /// Gets or sets the schema identifier used by consumers to decode this metric event.
+    /// </summary>
     [JsonPropertyName("type")]
     public string Type { get; set; } = "io.nats.server.metric.v1.service_latency";
 
+    /// <summary>
+    /// Gets or sets the account or identity that initiated the service request.
+    /// </summary>
     [JsonPropertyName("requestor")]
     public string Requestor { get; set; } = string.Empty;
 
+    /// <summary>
+    /// Gets or sets the service identity that responded to the request.
+    /// </summary>
     [JsonPropertyName("responder")]
     public string Responder { get; set; } = string.Empty;
 
+    /// <summary>
+    /// Gets or sets the service response status code reported in the advisory.
+    /// </summary>
     [JsonPropertyName("status")]
     public int Status { get; set; } = 200;
 
+    /// <summary>
+    /// Gets or sets service execution latency in nanoseconds on the responder side.
+    /// </summary>
     [JsonPropertyName("svc_latency")]
     public long ServiceLatencyNanos { get; set; }
 
+    /// <summary>
+    /// Gets or sets end-to-end request latency in nanoseconds from requestor to response.
+    /// </summary>
     [JsonPropertyName("total_latency")]
     public long TotalLatencyNanos { get; set; }
 }
 
+/// <summary>
+/// Sampling and payload helpers for service import latency metrics.
+/// </summary>
 public static class LatencyTracker
 {
+    /// <summary>
+    /// Determines whether a request should emit latency telemetry based on configured sampling.
+    /// </summary>
+    /// <param name="latency">Service latency sampling configuration from the export definition.</param>
     public static bool ShouldSample(ServiceLatency latency)
     {
         if (latency.SamplingPercentage <= 0) return false;
@@ -32,6 +60,13 @@ public static class LatencyTracker
         return Random.Shared.Next(100) < latency.SamplingPercentage;
     }
 
+    /// <summary>
+    /// Builds a service latency advisory payload from measured service and end-to-end durations.
+    /// </summary>
+    /// <param name="requestor">Identity of the requesting account or client.</param>
+    /// <param name="responder">Identity of the exported service that handled the request.</param>
+    /// <param name="serviceLatency">Time spent processing the request by the service itself.</param>
+    /// <param name="totalLatency">Full request round-trip latency as observed by the server.</param>
     public static ServiceLatencyMsg BuildLatencyMsg(
         string requestor, string responder,
         TimeSpan serviceLatency, TimeSpan totalLatency)

src/NATS.Server/Imports/ResponseRouter.cs

@@ -30,6 +30,9 @@ public static class ResponseRouter
     /// Creates a response service import that maps the generated reply prefix
     /// back to the original reply subject on the requesting account.
     /// </summary>
+    /// <param name="exporterAccount">Exporter account that stores temporary response imports.</param>
+    /// <param name="originalImport">Original service import that triggered the response path.</param>
+    /// <param name="originalReply">Original reply subject to route responder messages back to.</param>
     public static ServiceImport CreateResponseImport(
         Account exporterAccount,
         ServiceImport originalImport,
@@ -57,6 +60,9 @@ public static class ResponseRouter
     /// For Singleton responses, this is called after the first reply is delivered.
     /// For Streamed/Chunked, it is called when the response stream ends.
     /// </summary>
+    /// <param name="account">Account that owns the temporary response import map.</param>
+    /// <param name="replyPrefix">Generated reply prefix key to remove.</param>
+    /// <param name="responseSi">Response service import being cleaned up.</param>
     public static void CleanupResponse(Account account, string replyPrefix, ServiceImport responseSi)
     {
         account.Exports.Responses.Remove(replyPrefix);

src/NATS.Server/Imports/ServiceExport.cs

@@ -4,10 +4,33 @@ namespace NATS.Server.Imports;
 
 public sealed class ServiceExport
 {
+    /// <summary>
+    /// Gets authorization rules controlling which accounts may import this service.
+    /// </summary>
     public ExportAuth Auth { get; init; } = new();
+
+    /// <summary>
+    /// Gets the exporting account that owns this service definition.
+    /// </summary>
     public Account? Account { get; init; }
+
+    /// <summary>
+    /// Gets the response mode expected from service responders (singleton or streamed).
+    /// </summary>
     public ServiceResponseType ResponseType { get; init; } = ServiceResponseType.Singleton;
+
+    /// <summary>
+    /// Gets the threshold used for service latency advisories and slow-response tracking.
+    /// </summary>
     public TimeSpan ResponseThreshold { get; init; } = TimeSpan.FromMinutes(2);
+
+    /// <summary>
+    /// Gets optional service latency sampling configuration for exported service calls.
+    /// </summary>
     public ServiceLatency? Latency { get; init; }
+
+    /// <summary>
+    /// Gets a value indicating whether distributed tracing headers are allowed for this service.
+    /// </summary>
     public bool AllowTrace { get; init; }
 }

src/NATS.Server/Imports/ServiceImport.cs

@@ -5,17 +5,30 @@ namespace NATS.Server.Imports;
 
 public sealed class ServiceImport
 {
+    /// <summary>Account that receives requests after the service import mapping is applied.</summary>
     public required Account DestinationAccount { get; init; }
+    /// <summary>Source subject exposed to the importing account.</summary>
     public required string From { get; init; }
+    /// <summary>Destination subject routed to the exporting account/service.</summary>
     public required string To { get; init; }
+    /// <summary>Optional subject transform applied when forwarding imported requests.</summary>
     public SubjectTransform? Transform { get; init; }
+    /// <summary>Export definition backing this import relationship.</summary>
     public ServiceExport? Export { get; init; }
+    /// <summary>Response behavior for imported service replies (singleton/stream/chunked).</summary>
     public ServiceResponseType ResponseType { get; init; } = ServiceResponseType.Singleton;
+    /// <summary>Subscription identifier bytes used for internal routing bookkeeping.</summary>
     public byte[]? Sid { get; set; }
+    /// <summary>Whether this import currently represents a generated response mapping.</summary>
     public bool IsResponse { get; init; }
+    /// <summary>Whether forwarding should use PUB semantics instead of request/reply.</summary>
     public bool UsePub { get; init; }
+    /// <summary>Whether the import definition has been invalidated.</summary>
     public bool Invalid { get; set; }
+    /// <summary>Whether this import can be shared across accounts/connections.</summary>
     public bool Share { get; init; }
+    /// <summary>Whether service latency/tracking metrics are enabled for this import.</summary>
     public bool Tracking { get; init; }
+    /// <summary>Last update timestamp stored as UTC ticks.</summary>
     public long TimestampTicks { get; set; }
 }

src/NATS.Server/Imports/StreamImport.cs

@@ -5,10 +5,33 @@ namespace NATS.Server.Imports;
 
 public sealed class StreamImport
 {
+    /// <summary>
+    /// Gets the exporting account that owns the imported stream subjects.
+    /// </summary>
     public required Account SourceAccount { get; init; }
+
+    /// <summary>
+    /// Gets the source subject pattern in the exporting account.
+    /// </summary>
     public required string From { get; init; }
+
+    /// <summary>
+    /// Gets the destination subject pattern mapped into the importing account.
+    /// </summary>
     public required string To { get; init; }
+
+    /// <summary>
+    /// Gets the optional transform applied while remapping imported stream subjects.
+    /// </summary>
     public SubjectTransform? Transform { get; init; }
+
+    /// <summary>
+    /// Gets a value indicating whether the import is restricted to publish operations.
+    /// </summary>
     public bool UsePub { get; init; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether this import has been marked invalid by validation logic.
+    /// </summary>
     public bool Invalid { get; set; }
 }

src/NATS.Server/Internal/SubjectTree/Nodes.cs

@@ -182,11 +182,17 @@ internal sealed class Leaf<T> : INode
         => Parts.MatchPartsAgainstFragment(parts, Suffix);
 
     // These should not be called on a leaf.
+    /// <inheritdoc />
     public void SetPrefix(ReadOnlySpan<byte> pre) => throw new InvalidOperationException("setPrefix called on leaf");
+    /// <inheritdoc />
     public void AddChild(byte c, INode n) => throw new InvalidOperationException("addChild called on leaf");
+    /// <inheritdoc />
     public ChildRef? FindChild(byte c) => throw new InvalidOperationException("findChild called on leaf");
+    /// <inheritdoc />
     public INode Grow() => throw new InvalidOperationException("grow called on leaf");
+    /// <inheritdoc />
     public void DeleteChild(byte c) => throw new InvalidOperationException("deleteChild called on leaf");
+    /// <inheritdoc />
     public INode? Shrink() => throw new InvalidOperationException("shrink called on leaf");
 }
 

src/NATS.Server/Internal/SubjectTree/Parts.cs

@@ -20,6 +20,8 @@ internal static class Parts
     /// Returns the pivot byte at the given position, or NoPivot if past end.
     /// Go reference: server/stree/util.go:pivot
     /// </summary>
+    /// <param name="subject">Subject bytes being inspected in the ART path.</param>
+    /// <param name="pos">Zero-based byte position to read from <paramref name="subject"/>.</param>
     internal static byte Pivot(ReadOnlySpan<byte> subject, int pos)
     {
         if (pos >= subject.Length) return NoPivot;
@@ -30,6 +32,8 @@ internal static class Parts
     /// Returns the length of the common prefix between two byte spans.
     /// Go reference: server/stree/util.go:commonPrefixLen
     /// </summary>
+    /// <param name="s1">First subject fragment.</param>
+    /// <param name="s2">Second subject fragment.</param>
     internal static int CommonPrefixLen(ReadOnlySpan<byte> s1, ReadOnlySpan<byte> s2)
     {
         var limit = Math.Min(s1.Length, s2.Length);
@@ -44,6 +48,7 @@ internal static class Parts
     /// <summary>
     /// Copy bytes helper.
     /// </summary>
+    /// <param name="src">Source bytes to clone into a managed array.</param>
     internal static byte[] CopyBytes(ReadOnlySpan<byte> src)
     {
         if (src.Length == 0) return [];
@@ -54,6 +59,7 @@ internal static class Parts
     /// Break a filter subject into parts based on wildcards (pwc '*' and fwc '>').
     /// Go reference: server/stree/parts.go:genParts
     /// </summary>
+    /// <param name="filter">Subscription filter subject that may include <c>*</c> or <c>&gt;</c> wildcards.</param>
     internal static ReadOnlyMemory<byte>[] GenParts(ReadOnlySpan<byte> filter)
     {
         var parts = new List<ReadOnlyMemory<byte>>();
@@ -142,6 +148,8 @@ internal static class Parts
     /// Match parts against a fragment (prefix for nodes or suffix for leaves).
     /// Go reference: server/stree/parts.go:matchParts
     /// </summary>
+    /// <param name="parts">Pre-tokenized wildcard and literal parts generated from a subject filter.</param>
+    /// <param name="frag">Current subject fragment being matched within the ART traversal.</param>
     internal static (ReadOnlyMemory<byte>[] RemainingParts, bool Matched) MatchPartsAgainstFragment(
         ReadOnlyMemory<byte>[] parts, ReadOnlySpan<byte> frag)
     {

src/NATS.Server/JetStream/Api/AdvisoryPublisher.cs

@@ -11,6 +11,10 @@ public sealed class AdvisoryPublisher
     private readonly Action<string, object> _publishAction;
     private long _publishCount;
 
+    /// <summary>
+    /// Creates an advisory publisher that emits advisory payloads through the provided callback.
+    /// </summary>
+    /// <param name="publishAction">Callback that publishes advisory objects to subjects.</param>
     public AdvisoryPublisher(Action<string, object> publishAction)
     {
         _publishAction = publishAction;
@@ -25,6 +29,8 @@ public sealed class AdvisoryPublisher
     /// Publishes a stream created advisory.
     /// Go reference: jetstream_api.go — advisory on stream creation.
     /// </summary>
+    /// <param name="streamName">Name of the created stream.</param>
+    /// <param name="detail">Optional stream-specific detail payload.</param>
     public void StreamCreated(string streamName, object? detail = null)
     {
         var subject = string.Format(Events.EventSubjects.JsAdvisoryStreamCreated, streamName);
@@ -41,6 +47,7 @@ public sealed class AdvisoryPublisher
     /// Publishes a stream deleted advisory.
     /// Go reference: jetstream_api.go — advisory on stream deletion.
     /// </summary>
+    /// <param name="streamName">Name of the deleted stream.</param>
     public void StreamDeleted(string streamName)
     {
         var subject = string.Format(Events.EventSubjects.JsAdvisoryStreamDeleted, streamName);
@@ -56,6 +63,8 @@ public sealed class AdvisoryPublisher
     /// Publishes a stream updated advisory.
     /// Go reference: jetstream_api.go — advisory on stream config update.
     /// </summary>
+    /// <param name="streamName">Name of the updated stream.</param>
+    /// <param name="detail">Optional update detail payload.</param>
     public void StreamUpdated(string streamName, object? detail = null)
     {
         var subject = string.Format(Events.EventSubjects.JsAdvisoryStreamUpdated, streamName);
@@ -72,6 +81,8 @@ public sealed class AdvisoryPublisher
     /// Publishes a consumer created advisory.
     /// Go reference: jetstream_api.go — advisory on consumer creation.
     /// </summary>
+    /// <param name="streamName">Parent stream name.</param>
+    /// <param name="consumerName">Created consumer name.</param>
     public void ConsumerCreated(string streamName, string consumerName)
     {
         var subject = string.Format(Events.EventSubjects.JsAdvisoryConsumerCreated, streamName, consumerName);
@@ -88,6 +99,8 @@ public sealed class AdvisoryPublisher
     /// Publishes a consumer deleted advisory.
     /// Go reference: jetstream_api.go — advisory on consumer deletion.
     /// </summary>
+    /// <param name="streamName">Parent stream name.</param>
+    /// <param name="consumerName">Deleted consumer name.</param>
     public void ConsumerDeleted(string streamName, string consumerName)
     {
         var subject = string.Format(Events.EventSubjects.JsAdvisoryConsumerDeleted, streamName, consumerName);

src/NATS.Server/JetStream/Api/ApiRateLimiter.cs

@@ -15,6 +15,11 @@ public sealed class ApiRateLimiter : IDisposable
     private readonly TimeSpan _dedupTtl;
     private readonly int _maxConcurrent;
 
+    /// <summary>
+    /// Creates a JetStream API limiter for request concurrency and short-window deduplication.
+    /// </summary>
+    /// <param name="maxConcurrent">Maximum concurrent API handlers allowed before rejecting new requests.</param>
+    /// <param name="dedupTtl">TTL window for request-id dedup cache entries.</param>
     public ApiRateLimiter(int maxConcurrent = 256, TimeSpan? dedupTtl = null)
     {
         _maxConcurrent = maxConcurrent;
@@ -33,6 +38,7 @@ public sealed class ApiRateLimiter : IDisposable
     /// Go reference: jetstream_api.go — non-blocking semaphore acquire; request is rejected
     /// immediately if no slots are available rather than queuing indefinitely.
     /// </summary>
+    /// <param name="ct">Cancellation token for the slot acquisition attempt.</param>
     public async Task<bool> TryAcquireAsync(CancellationToken ct = default)
     {
         return await _semaphore.WaitAsync(0, ct);
@@ -51,6 +57,7 @@ public sealed class ApiRateLimiter : IDisposable
     /// Returns the cached response if found and not expired, null otherwise.
     /// Go reference: jetstream_api.go — dedup cache is keyed by Nats-Msg-Id header value.
     /// </summary>
+    /// <param name="requestId">Message-id dedup key from the request.</param>
     public JetStreamApiResponse? GetCachedResponse(string? requestId)
     {
         if (string.IsNullOrEmpty(requestId))
@@ -73,6 +80,8 @@ public sealed class ApiRateLimiter : IDisposable
     /// Go reference: jetstream_api.go — response is stored with a timestamp so that
     /// subsequent requests with the same Nats-Msg-Id within the TTL window get the same result.
     /// </summary>
+    /// <param name="requestId">Message-id dedup key from the request.</param>
+    /// <param name="response">Response payload to reuse for duplicate requests within the dedup window.</param>
     public void CacheResponse(string? requestId, JetStreamApiResponse response)
     {
         if (string.IsNullOrEmpty(requestId))
@@ -99,6 +108,9 @@ public sealed class ApiRateLimiter : IDisposable
         return removed;
     }
 
+    /// <summary>
+    /// Releases semaphore resources held by the rate limiter.
+    /// </summary>
     public void Dispose()
     {
         _semaphore.Dispose();

src/NATS.Server/JetStream/Api/ClusteredRequestProcessor.cs

@@ -18,6 +18,10 @@ public sealed class ClusteredRequestProcessor
     private readonly TimeSpan _timeout;
     private int _pendingCount;
 
+    /// <summary>
+    /// Creates a clustered request processor with a configurable wait timeout.
+    /// </summary>
+    /// <param name="timeout">Optional timeout for waiting on RAFT apply callbacks per request.</param>
     public ClusteredRequestProcessor(TimeSpan? timeout = null)
     {
         _timeout = timeout ?? DefaultTimeout;
@@ -47,6 +51,8 @@ public sealed class ClusteredRequestProcessor
     /// Go reference: jetstream_cluster.go:7620 — the goroutine waits on a per-request channel
     /// with a context deadline derived from the cluster's JSApiTimeout option.
     /// </summary>
+    /// <param name="requestId">Correlation id returned by <see cref="RegisterPending"/>.</param>
+    /// <param name="ct">Cancellation token for caller-initiated cancellation.</param>
     public async Task<JetStreamApiResponse> WaitForResultAsync(string requestId, CancellationToken ct = default)
     {
         if (!_pending.TryGetValue(requestId, out var tcs))
@@ -76,6 +82,8 @@ public sealed class ClusteredRequestProcessor
     /// Go reference: jetstream_cluster.go:7620 — the RAFT apply callback resolves the pending
     /// request channel so the waiting goroutine can return the response to the caller.
     /// </summary>
+    /// <param name="requestId">Pending request correlation id.</param>
+    /// <param name="response">Response generated after RAFT proposal application.</param>
     public bool DeliverResult(string requestId, JetStreamApiResponse response)
     {
         if (!_pending.TryRemove(requestId, out var tcs))
@@ -91,6 +99,7 @@ public sealed class ClusteredRequestProcessor
     /// Go reference: jetstream_cluster.go — when RAFT leadership changes, all in-flight
     /// proposals must be failed with a "not leader" or "cancelled" error.
     /// </summary>
+    /// <param name="reason">Reason string returned to callers in the synthesized 503 response.</param>
     public void CancelAll(string reason = "leadership changed")
     {
         foreach (var (key, tcs) in _pending)

src/NATS.Server/JetStream/Api/Handlers/AccountControlApiHandlers.cs

@@ -2,9 +2,16 @@ namespace NATS.Server.JetStream.Api.Handlers;
 
 public static class AccountControlApiHandlers
 {
+    /// <summary>
+    /// Handles account-wide server-removal control requests.
+    /// </summary>
     public static JetStreamApiResponse HandleServerRemove()
         => JetStreamApiResponse.SuccessResponse();
 
+    /// <summary>
+    /// Handles account purge requests routed via API subject.
+    /// </summary>
+    /// <param name="subject">API subject containing account purge target.</param>
     public static JetStreamApiResponse HandleAccountPurge(string subject)
     {
         if (!subject.StartsWith(JetStreamApiSubjects.AccountPurge, StringComparison.Ordinal))
@@ -14,6 +21,10 @@ public static class AccountControlApiHandlers
         return account.Length == 0 ? JetStreamApiResponse.NotFound(subject) : JetStreamApiResponse.SuccessResponse();
     }
 
+    /// <summary>
+    /// Handles account stream-move requests routed via API subject.
+    /// </summary>
+    /// <param name="subject">API subject containing account move target.</param>
     public static JetStreamApiResponse HandleAccountStreamMove(string subject)
     {
         if (!subject.StartsWith(JetStreamApiSubjects.AccountStreamMove, StringComparison.Ordinal))
@@ -23,6 +34,10 @@ public static class AccountControlApiHandlers
         return account.Length == 0 ? JetStreamApiResponse.NotFound(subject) : JetStreamApiResponse.SuccessResponse();
     }
 
+    /// <summary>
+    /// Handles account stream-move cancellation requests routed via API subject.
+    /// </summary>
+    /// <param name="subject">API subject containing account move-cancel target.</param>
     public static JetStreamApiResponse HandleAccountStreamMoveCancel(string subject)
     {
         if (!subject.StartsWith(JetStreamApiSubjects.AccountStreamMoveCancel, StringComparison.Ordinal))

src/NATS.Server/JetStream/Api/Handlers/ClusterControlApiHandlers.cs

@@ -2,12 +2,21 @@ namespace NATS.Server.JetStream.Api.Handlers;
 
 public static class ClusterControlApiHandlers
 {
+    /// <summary>
+    /// Handles meta-group leader stepdown requests.
+    /// </summary>
+    /// <param name="meta">JetStream meta group receiving the stepdown signal.</param>
     public static JetStreamApiResponse HandleMetaLeaderStepdown(JetStream.Cluster.JetStreamMetaGroup meta)
     {
         meta.StepDown();
         return JetStreamApiResponse.SuccessResponse();
     }
 
+    /// <summary>
+    /// Handles stream leader stepdown requests routed via API subject.
+    /// </summary>
+    /// <param name="subject">API subject containing stream leader-stepdown target.</param>
+    /// <param name="streams">Stream manager used to execute the stepdown action.</param>
     public static JetStreamApiResponse HandleStreamLeaderStepdown(string subject, StreamManager streams)
     {
         if (!subject.StartsWith(JetStreamApiSubjects.StreamLeaderStepdown, StringComparison.Ordinal))
@@ -21,6 +30,10 @@ public static class ClusterControlApiHandlers
         return JetStreamApiResponse.SuccessResponse();
     }
 
+    /// <summary>
+    /// Handles stream peer removal requests routed via API subject.
+    /// </summary>
+    /// <param name="subject">API subject containing stream peer-removal target.</param>
     public static JetStreamApiResponse HandleStreamPeerRemove(string subject)
     {
         if (!subject.StartsWith(JetStreamApiSubjects.StreamPeerRemove, StringComparison.Ordinal))
@@ -30,6 +43,10 @@ public static class ClusterControlApiHandlers
         return stream.Length == 0 ? JetStreamApiResponse.NotFound(subject) : JetStreamApiResponse.SuccessResponse();
     }
 
+    /// <summary>
+    /// Handles consumer leader stepdown requests routed via API subject.
+    /// </summary>
+    /// <param name="subject">API subject containing stream/consumer stepdown target.</param>
     public static JetStreamApiResponse HandleConsumerLeaderStepdown(string subject)
     {
         if (!subject.StartsWith(JetStreamApiSubjects.ConsumerLeaderStepdown, StringComparison.Ordinal))

src/NATS.Server/JetStream/Cluster/AssignmentCodec.cs

@@ -49,6 +49,7 @@ public static class AssignmentCodec
     /// Go reference: jetstream_cluster.go:8703 encodeAddStreamAssignment —
     /// marshals the assignment struct (with ConfigJSON) to JSON.
     /// </summary>
+    /// <param name="sa">Stream assignment payload to encode for meta-cluster replication.</param>
     public static byte[] EncodeStreamAssignment(StreamAssignment sa)
         => JsonSerializer.SerializeToUtf8Bytes(sa, SerializerOptions);
 
@@ -58,6 +59,7 @@ public static class AssignmentCodec
     /// Go reference: jetstream_cluster.go:8733 decodeStreamAssignment —
     /// json.Unmarshal(buf, &amp;sa); returns nil, err on failure.
     /// </summary>
+    /// <param name="data">UTF-8 encoded stream assignment bytes from RAFT metadata messages.</param>
     public static StreamAssignment? DecodeStreamAssignment(ReadOnlySpan<byte> data)
     {
         if (data.IsEmpty)
@@ -84,6 +86,7 @@ public static class AssignmentCodec
     /// Go reference: jetstream_cluster.go:9175 encodeAddConsumerAssignment —
     /// marshals the assignment struct to JSON.
     /// </summary>
+    /// <param name="ca">Consumer assignment payload to encode for cluster propagation.</param>
     public static byte[] EncodeConsumerAssignment(ConsumerAssignment ca)
         => JsonSerializer.SerializeToUtf8Bytes(ca, SerializerOptions);
 
@@ -93,6 +96,7 @@ public static class AssignmentCodec
     /// Go reference: jetstream_cluster.go:9195 decodeConsumerAssignment —
     /// json.Unmarshal(buf, &amp;ca); returns nil, err on failure.
     /// </summary>
+    /// <param name="data">UTF-8 encoded consumer assignment bytes from metadata updates.</param>
     public static ConsumerAssignment? DecodeConsumerAssignment(ReadOnlySpan<byte> data)
     {
         if (data.IsEmpty)
@@ -128,6 +132,8 @@ public static class AssignmentCodec
     /// s2.NewWriter used to compress large consumer assignment payloads; the caller
     /// prepends the assignCompressedConsumerOp opcode byte as a similar kind of marker.
     /// </summary>
+    /// <param name="data">Uncompressed assignment payload bytes.</param>
+    /// <param name="threshold">Minimum byte size required before compression is applied.</param>
     public static byte[] CompressIfLarge(byte[] data, int threshold = 1024)
     {
         if (data.Length <= threshold)
@@ -148,6 +154,7 @@ public static class AssignmentCodec
     /// s2.NewReader used to decompress consumer assignment payloads that were compressed
     /// before being proposed to the meta RAFT group.
     /// </summary>
+    /// <param name="data">Compressed-or-plain payload bytes received from cluster metadata transport.</param>
     public static byte[] DecompressIfNeeded(byte[] data)
     {
         if (data.Length > 0 && data[0] == CompressedMarker)

src/NATS.Server/JetStream/Cluster/JetStreamClusterMonitor.cs

@@ -30,11 +30,22 @@ public sealed class JetStreamClusterMonitor
     /// </summary>
     public int ProcessedCount { get { lock (_processedLock) return _processedCount; } }
 
+    /// <summary>
+    /// Creates a cluster monitor with a null logger for lightweight test and host setups.
+    /// </summary>
+    /// <param name="meta">Meta-group state container receiving assignment updates.</param>
+    /// <param name="entries">RAFT entry channel consumed by the monitor loop.</param>
     public JetStreamClusterMonitor(JetStreamMetaGroup meta, ChannelReader<RaftLogEntry> entries)
         : this(meta, entries, NullLogger<JetStreamClusterMonitor>.Instance)
     {
     }
 
+    /// <summary>
+    /// Creates a cluster monitor with explicit logger injection.
+    /// </summary>
+    /// <param name="meta">Meta-group state container receiving assignment updates.</param>
+    /// <param name="entries">RAFT entry channel consumed by the monitor loop.</param>
+    /// <param name="logger">Logger for malformed entry and state-application diagnostics.</param>
     public JetStreamClusterMonitor(
         JetStreamMetaGroup meta,
         ChannelReader<RaftLogEntry> entries,
@@ -50,6 +61,7 @@ public sealed class JetStreamClusterMonitor
     /// Each entry is applied synchronously before the next is read.
     /// Returns normally (without throwing) when <paramref name="ct"/> is cancelled.
     /// </summary>
+    /// <param name="ct">Cancellation token used to stop the monitor loop.</param>
     public async Task StartAsync(CancellationToken ct)
     {
         try
@@ -75,6 +87,8 @@ public sealed class JetStreamClusterMonitor
     /// <paramref name="targetCount"/>. Returns immediately when the target is already met.
     /// Used by tests to synchronise without sleeping.
     /// </summary>
+    /// <param name="targetCount">Minimum processed-entry count to wait for.</param>
+    /// <param name="ct">Cancellation token for aborting the wait.</param>
     public Task WaitForProcessedAsync(int targetCount, CancellationToken ct)
     {
         // Fast path — already done.

src/NATS.Server/JetStream/Cluster/PlacementEngine.cs

@@ -31,6 +31,11 @@ public static class PlacementEngine
     ///      Overloaded peers are tried only after preferred candidates are exhausted.
     ///   8. Throw InvalidOperationException if fewer than replicas peers can be selected.
     /// </summary>
+    /// <param name="groupName">RAFT group name being placed.</param>
+    /// <param name="replicas">Required number of replicas/peers.</param>
+    /// <param name="availablePeers">Available cluster peers considered for placement.</param>
+    /// <param name="policy">Optional placement policy with cluster/tag constraints.</param>
+    /// <param name="assetCostWeight">Per-asset storage penalty used in scoring.</param>
     public static RaftGroup SelectPeerGroup(
         string groupName,
         int replicas,
@@ -201,10 +206,15 @@ public static class PlacementEngine
 /// </summary>
 public sealed class PeerInfo
 {
+    /// <summary>Unique peer identifier used in RAFT group membership.</summary>
     public required string PeerId { get; init; }
+    /// <summary>Cluster name/partition where this peer resides.</summary>
     public string Cluster { get; set; } = string.Empty;
+    /// <summary>Capability and topology tags advertised by this peer.</summary>
     public HashSet<string> Tags { get; init; } = new(StringComparer.OrdinalIgnoreCase);
+    /// <summary>Whether this peer is currently eligible for new assignments.</summary>
     public bool Available { get; set; } = true;
+    /// <summary>Approximate remaining storage available for new assets.</summary>
     public long AvailableStorage { get; set; } = long.MaxValue;
 
     /// <summary>
@@ -228,8 +238,11 @@ public sealed class PeerInfo
 /// </summary>
 public sealed class PlacementPolicy
 {
+    /// <summary>Optional cluster affinity constraint.</summary>
     public string? Cluster { get; set; }
+    /// <summary>Required tags that must all be present on a candidate peer.</summary>
     public HashSet<string>? Tags { get; set; }
+    /// <summary>Tags that disqualify a candidate peer when present.</summary>
     public HashSet<string>? ExcludeTags { get; set; }
 
     /// <summary>

src/NATS.Server/JetStream/Consumers/FilterSkipTracker.cs

@@ -17,6 +17,11 @@ public sealed class FilterSkipTracker
     private long _matchCount;
     private long _skipCount;
 
+    /// <summary>
+    /// Creates a filter-skip tracker for single or multi-subject consumer filters.
+    /// </summary>
+    /// <param name="filterSubject">Optional single filter subject for consumer delivery.</param>
+    /// <param name="filterSubjects">Optional multi-subject filter set for consumer delivery.</param>
     public FilterSkipTracker(string? filterSubject = null, IReadOnlyList<string>? filterSubjects = null)
     {
         _filterSubject = filterSubject;
@@ -46,6 +51,7 @@ public sealed class FilterSkipTracker
     /// Uses SubjectMatch.MatchLiteral for NATS token-based matching.
     /// Go reference: consumer.go isFilteredMatch.
     /// </summary>
+    /// <param name="subject">Message subject being evaluated for this consumer.</param>
     public bool ShouldDeliver(string subject)
     {
         if (!HasFilter)
@@ -79,6 +85,7 @@ public sealed class FilterSkipTracker
     /// <summary>
     /// Records a skipped sequence for gap tracking.
     /// </summary>
+    /// <param name="sequence">Stream sequence skipped due to filter mismatch.</param>
     public void RecordSkip(ulong sequence)
     {
         _skippedSequences.Add(sequence);
@@ -88,6 +95,7 @@ public sealed class FilterSkipTracker
     /// Returns the next unskipped sequence >= startSeq.
     /// Used to find the next deliverable message efficiently.
     /// </summary>
+    /// <param name="startSeq">Candidate sequence to begin searching from.</param>
     public ulong NextUnskippedSequence(ulong startSeq)
     {
         var seq = startSeq;
@@ -100,6 +108,7 @@ public sealed class FilterSkipTracker
     /// Clears skipped sequences below the given floor (e.g., ack floor).
     /// Prevents unbounded growth.
     /// </summary>
+    /// <param name="floor">Inclusive lower bound; skipped sequences below this value are removed.</param>
     public void PurgeBelow(ulong floor)
     {
         _skippedSequences.RemoveWhere(s => s < floor);

src/NATS.Server/JetStream/Consumers/SampleTracker.cs

@@ -17,6 +17,8 @@ public sealed class SampleTracker
     /// Creates a sample tracker with the given rate (0.0 to 1.0).
     /// Use ParseSampleFrequency to convert string like "1%" to rate.
     /// </summary>
+    /// <param name="sampleRate">Sampling probability as a fraction from 0.0 to 1.0.</param>
+    /// <param name="random">Optional random source for deterministic testability.</param>
     public SampleTracker(double sampleRate, Random? random = null)
     {
         _sampleRate = Math.Clamp(sampleRate, 0.0, 1.0);
@@ -61,6 +63,9 @@ public sealed class SampleTracker
     /// Records a latency measurement for a sampled delivery.
     /// Returns a LatencySample for advisory publication.
     /// </summary>
+    /// <param name="deliveryLatency">Observed delivery latency for the sampled message.</param>
+    /// <param name="sequence">Stream sequence number of the sampled message.</param>
+    /// <param name="subject">Subject delivered to the consumer.</param>
     public LatencySample RecordLatency(TimeSpan deliveryLatency, ulong sequence, string subject)
     {
         return new LatencySample
@@ -78,6 +83,7 @@ public sealed class SampleTracker
     /// Returns 0.0 for invalid or empty strings.
     /// Go reference: consumer.go parseSampleFrequency.
     /// </summary>
+    /// <param name="frequency">Human-readable percentage string.</param>
     public static double ParseSampleFrequency(string? frequency)
     {
         if (string.IsNullOrWhiteSpace(frequency))
@@ -104,8 +110,12 @@ public sealed class SampleTracker
 /// </summary>
 public sealed class LatencySample
 {
+    /// <summary>Stream sequence number of the sampled message.</summary>
     public ulong Sequence { get; init; }
+    /// <summary>Subject delivered to the consumer.</summary>
     public string Subject { get; init; } = string.Empty;
+    /// <summary>Observed delivery latency for this sample.</summary>
     public TimeSpan DeliveryLatency { get; init; }
+    /// <summary>UTC timestamp when the sample was captured.</summary>
     public DateTime SampledAtUtc { get; init; }
 }

src/NATS.Server/JetStream/Consumers/TokenBucketRateLimiter.cs

@@ -50,6 +50,7 @@ public sealed class TokenBucketRateLimiter
     /// Returns true if tokens were available (message can be sent).
     /// Returns false if not enough tokens (caller should wait).
     /// </summary>
+    /// <param name="bytes">Number of payload bytes to reserve from the token bucket.</param>
     public bool TryConsume(long bytes)
     {
         if (BytesPerSecond <= 0) return true; // Unlimited
@@ -69,6 +70,7 @@ public sealed class TokenBucketRateLimiter
     /// <summary>
     /// Returns the estimated wait time until enough tokens are available.
     /// </summary>
+    /// <param name="bytes">Number of bytes needed before send can proceed.</param>
     public TimeSpan EstimateWait(long bytes)
     {
         if (BytesPerSecond <= 0) return TimeSpan.Zero;
@@ -87,6 +89,8 @@ public sealed class TokenBucketRateLimiter
     /// <summary>
     /// Waits until enough tokens are available, then consumes them.
     /// </summary>
+    /// <param name="bytes">Number of payload bytes that must be available.</param>
+    /// <param name="ct">Cancellation token to stop waiting when request processing is canceled.</param>
     public async ValueTask WaitForTokensAsync(long bytes, CancellationToken ct = default)
     {
         if (BytesPerSecond <= 0) return;
@@ -107,6 +111,8 @@ public sealed class TokenBucketRateLimiter
     /// Updates the rate dynamically.
     /// Go reference: consumer.go — rate can change on config update.
     /// </summary>
+    /// <param name="bytesPerSecond">New throughput limit in bytes per second.</param>
+    /// <param name="burstSize">Optional new burst ceiling; defaults to two seconds of throughput.</param>
     public void UpdateRate(long bytesPerSecond, long burstSize = 0)
     {
         lock (_lock)

src/NATS.Server/JetStream/Consumers/WaitingRequestQueue.cs

@@ -25,6 +25,7 @@ public sealed record PullRequest(
     public void ConsumeBatch() => RemainingBatch--;
 
     /// <summary>Subtract delivered bytes from remaining byte budget.</summary>
+    /// <param name="bytes">Delivered payload bytes to subtract from this pull request budget.</param>
     public void ConsumeBytes(long bytes) => RemainingBytes -= bytes;
 }
 
@@ -38,11 +39,25 @@ public sealed class WaitingRequestQueue
 {
     private readonly LinkedList<PullRequest> _queue = new();
 
+    /// <summary>
+    /// Gets the current number of queued pull requests awaiting delivery.
+    /// </summary>
     public int Count => _queue.Count;
+
+    /// <summary>
+    /// Gets a value indicating whether there are no pending pull requests.
+    /// </summary>
     public bool IsEmpty => _queue.Count == 0;
 
+    /// <summary>
+    /// Enqueues a pull request at the tail of the FIFO wait queue.
+    /// </summary>
+    /// <param name="request">Pull request to add.</param>
     public void Enqueue(PullRequest request) => _queue.AddLast(request);
 
+    /// <summary>
+    /// Dequeues the oldest pending pull request, or <see langword="null"/> when empty.
+    /// </summary>
     public PullRequest? TryDequeue()
     {
         if (_queue.Count == 0) return null;
@@ -51,6 +66,10 @@ public sealed class WaitingRequestQueue
         return first;
     }
 
+    /// <summary>
+    /// Removes expired pull requests whose deadline is at or before <paramref name="now"/>.
+    /// </summary>
+    /// <param name="now">Current timestamp used for expiry comparison.</param>
     public void RemoveExpired(DateTimeOffset now)
     {
         var node = _queue.First;

src/NATS.Server/JetStream/InterestRetentionPolicy.cs

@@ -18,6 +18,8 @@ public sealed class InterestRetentionPolicy
     /// <summary>
     /// Register a consumer's interest in a subject pattern.
     /// </summary>
+    /// <param name="consumer">Durable or ephemeral consumer name whose interest is tracked.</param>
+    /// <param name="filterSubject">Consumer filter subject used to determine message relevance.</param>
     public void RegisterInterest(string consumer, string filterSubject)
     {
         _interests[consumer] = filterSubject;
@@ -26,6 +28,7 @@ public sealed class InterestRetentionPolicy
     /// <summary>
     /// Remove a consumer's interest (e.g., on deletion).
     /// </summary>
+    /// <param name="consumer">Consumer identifier to remove from interest tracking.</param>
     public void UnregisterInterest(string consumer)
     {
         _interests.Remove(consumer);
@@ -34,6 +37,8 @@ public sealed class InterestRetentionPolicy
     /// <summary>
     /// Record that a consumer has acknowledged delivery of a sequence.
     /// </summary>
+    /// <param name="consumer">Consumer that acknowledged delivery.</param>
+    /// <param name="seq">Stream sequence number being acknowledged.</param>
     public void AcknowledgeDelivery(string consumer, ulong seq)
     {
         if (!_acks.TryGetValue(seq, out var ackedBy))
@@ -49,6 +54,8 @@ public sealed class InterestRetentionPolicy
     /// interested consumer has NOT yet acknowledged it).
     /// A consumer is "interested" if its filter subject matches the message subject.
     /// </summary>
+    /// <param name="seq">Stream sequence being evaluated for retention eligibility.</param>
+    /// <param name="msgSubject">Published subject of the message at <paramref name="seq"/>.</param>
     public bool ShouldRetain(ulong seq, string msgSubject)
     {
         _acks.TryGetValue(seq, out var ackedBy);

src/NATS.Server/JetStream/JetStreamProfiler.cs

@@ -19,16 +19,36 @@ public static class JetStreamProfiler
     private static long _ackDeliverTicks;
     private static long _totalProcessMessageTicks;
 
+    /// <summary>Records ticks spent in stream subject-to-stream resolution.</summary>
+    /// <param name="ticks">Elapsed stopwatch ticks.</param>
     public static void RecordFindBySubject(long ticks) => Interlocked.Add(ref _findBySubjectTicks, ticks);
+    /// <summary>Records ticks spent loading stream state metadata.</summary>
+    /// <param name="ticks">Elapsed stopwatch ticks.</param>
     public static void RecordGetState(long ticks) => Interlocked.Add(ref _getStateTicks, ticks);
+    /// <summary>Records ticks spent appending to stream storage.</summary>
+    /// <param name="ticks">Elapsed stopwatch ticks.</param>
     public static void RecordAppend(long ticks) => Interlocked.Add(ref _appendTicks, ticks);
+    /// <summary>Records ticks spent enforcing stream retention/limit policies.</summary>
+    /// <param name="ticks">Elapsed stopwatch ticks.</param>
     public static void RecordEnforcePolicies(long ticks) => Interlocked.Add(ref _enforcePoliciesTicks, ticks);
+    /// <summary>Records residual capture overhead not attributed to named stages.</summary>
+    /// <param name="ticks">Elapsed stopwatch ticks.</param>
     public static void RecordCaptureOverhead(long ticks) => Interlocked.Add(ref _captureOverheadTicks, ticks);
+    /// <summary>Records ticks spent serializing publish-related JSON responses/events.</summary>
+    /// <param name="ticks">Elapsed stopwatch ticks.</param>
     public static void RecordJsonSerialize(long ticks) => Interlocked.Add(ref _jsonSerializeTicks, ticks);
+    /// <summary>Records ticks spent in ack-delivery and ack-path bookkeeping.</summary>
+    /// <param name="ticks">Elapsed stopwatch ticks.</param>
     public static void RecordAckDeliver(long ticks) => Interlocked.Add(ref _ackDeliverTicks, ticks);
+    /// <summary>Records total ticks spent processing a message end-to-end.</summary>
+    /// <param name="ticks">Elapsed stopwatch ticks.</param>
     public static void RecordTotalProcessMessage(long ticks) => Interlocked.Add(ref _totalProcessMessageTicks, ticks);
+    /// <summary>Increments the total processed-call counter.</summary>
     public static void IncrementCalls() => Interlocked.Increment(ref _totalCalls);
 
+    /// <summary>
+    /// Returns a formatted profile report and resets all accumulated counters.
+    /// </summary>
     public static string DumpAndReset()
     {
         var calls = Interlocked.Exchange(ref _totalCalls, 0);

src/NATS.Server/JetStream/JetStreamService.cs

@@ -44,7 +44,14 @@ public sealed class JetStreamService : IAsyncDisposable
     private readonly ILogger<JetStreamService> _logger;
     private List<string> _registeredApiSubjects = [];
 
+    /// <summary>
+    /// Gets the internal client used for local system publications, when configured.
+    /// </summary>
     public InternalClient? InternalClient { get; }
+
+    /// <summary>
+    /// Gets a value indicating whether JetStream API subjects are currently registered.
+    /// </summary>
     public bool IsRunning { get; private set; }
 
     /// <summary>
@@ -77,11 +84,22 @@ public sealed class JetStreamService : IAsyncDisposable
     /// </summary>
     public long MaxStore => _options.MaxFileStore;
 
+    /// <summary>
+    /// Creates a JetStream service using null logging for lightweight host wiring.
+    /// </summary>
+    /// <param name="options">JetStream configuration limits and storage settings.</param>
+    /// <param name="internalClient">Optional internal client for server-generated JetStream API traffic.</param>
     public JetStreamService(JetStreamOptions options, InternalClient? internalClient = null)
         : this(options, internalClient, NullLoggerFactory.Instance)
     {
     }
 
+    /// <summary>
+    /// Creates a JetStream service with explicit logging factory control.
+    /// </summary>
+    /// <param name="options">JetStream configuration limits and storage settings.</param>
+    /// <param name="internalClient">Optional internal client for server-generated JetStream API traffic.</param>
+    /// <param name="loggerFactory">Logger factory used to create component loggers.</param>
     public JetStreamService(JetStreamOptions options, InternalClient? internalClient, ILoggerFactory loggerFactory)
     {
         _options = options;
@@ -92,6 +110,10 @@ public sealed class JetStreamService : IAsyncDisposable
     // Maps to Go's enableJetStream() in server/jetstream.go:414-523.
     // Validates the store directory, creates it if absent, then registers all
     // $JS.API.> subjects so inbound API messages can be routed.
+    /// <summary>
+    /// Starts JetStream by validating storage and registering all JetStream API subjects.
+    /// </summary>
+    /// <param name="ct">Cancellation token for startup flow control.</param>
     public Task StartAsync(CancellationToken ct)
     {
         if (IsRunning)
@@ -138,6 +160,9 @@ public sealed class JetStreamService : IAsyncDisposable
 
     // Maps to Go's shutdown path in jetstream.go.
     // Clears registered subjects and marks the service as not running.
+    /// <summary>
+    /// Stops JetStream and removes registered API subjects.
+    /// </summary>
     public ValueTask DisposeAsync()
     {
         _registeredApiSubjects = [];

src/NATS.Server/JetStream/JsVersioning.cs

@@ -34,6 +34,7 @@ public static class JsVersioning
     /// Returns the required API level string from metadata, or empty if absent.
     /// Go: getRequiredApiLevel (jetstream_versioning.go:28)
     /// </summary>
+    /// <param name="metadata">Metadata dictionary that may contain the required-level key.</param>
     public static string GetRequiredApiLevel(Dictionary<string, string>? metadata)
     {
         if (metadata != null && metadata.TryGetValue(RequiredLevelKey, out var level) && level.Length > 0)
@@ -45,6 +46,7 @@ public static class JsVersioning
     /// Returns whether the required API level is supported by this server.
     /// Go: supportsRequiredApiLevel (jetstream_versioning.go:36)
     /// </summary>
+    /// <param name="metadata">Metadata dictionary that may contain required-level information.</param>
     public static bool SupportsRequiredApiLevel(Dictionary<string, string>? metadata)
     {
         var level = GetRequiredApiLevel(metadata);
@@ -60,6 +62,7 @@ public static class JsVersioning
     /// Clears dynamic fields (server version/level) and sets the required API level.
     /// Go: setStaticStreamMetadata (jetstream_versioning.go:44)
     /// </summary>
+    /// <param name="cfg">Stream configuration to mutate with static version metadata.</param>
     public static void SetStaticStreamMetadata(StreamConfig cfg)
     {
         if (cfg.Metadata == null)
@@ -98,6 +101,7 @@ public static class JsVersioning
     /// The original config is not modified.
     /// Go: setDynamicStreamMetadata (jetstream_versioning.go:88)
     /// </summary>
+    /// <param name="cfg">Source stream configuration.</param>
     public static StreamConfig SetDynamicStreamMetadata(StreamConfig cfg)
     {
         // Shallow copy the config
@@ -118,6 +122,8 @@ public static class JsVersioning
     /// Removes dynamic fields. If prevCfg has no metadata, removes the key from cfg.
     /// Go: copyStreamMetadata (jetstream_versioning.go:110)
     /// </summary>
+    /// <param name="cfg">Target stream configuration to update.</param>
+    /// <param name="prevCfg">Previous stream configuration whose required-level metadata is preserved.</param>
     public static void CopyStreamMetadata(StreamConfig cfg, StreamConfig? prevCfg)
     {
         if (cfg.Metadata != null)
@@ -129,6 +135,7 @@ public static class JsVersioning
     /// Sets static (stored) versioning metadata on a consumer config.
     /// Go: setStaticConsumerMetadata (jetstream_versioning.go:136)
     /// </summary>
+    /// <param name="cfg">Consumer configuration to mutate with static version metadata.</param>
     public static void SetStaticConsumerMetadata(ConsumerConfig cfg)
     {
         if (cfg.Metadata == null)
@@ -154,6 +161,7 @@ public static class JsVersioning
     /// Returns a copy of the consumer config with dynamic metadata fields added.
     /// Go: setDynamicConsumerMetadata (jetstream_versioning.go:164)
     /// </summary>
+    /// <param name="cfg">Source consumer configuration.</param>
     public static ConsumerConfig SetDynamicConsumerMetadata(ConsumerConfig cfg)
     {
         var newCfg = ShallowCopyConsumer(cfg);
@@ -173,6 +181,8 @@ public static class JsVersioning
     /// Removes dynamic fields.
     /// Go: copyConsumerMetadata (jetstream_versioning.go:198)
     /// </summary>
+    /// <param name="cfg">Target consumer configuration to update.</param>
+    /// <param name="prevCfg">Previous consumer configuration whose required-level metadata is preserved.</param>
     public static void CopyConsumerMetadata(ConsumerConfig cfg, ConsumerConfig? prevCfg)
     {
         if (cfg.Metadata != null)
@@ -184,6 +194,7 @@ public static class JsVersioning
     /// Removes dynamic metadata fields (server version and level) from a metadata dictionary.
     /// Go: deleteDynamicMetadata (jetstream_versioning.go:222)
     /// </summary>
+    /// <param name="metadata">Metadata dictionary to clean.</param>
     public static void DeleteDynamicMetadata(Dictionary<string, string> metadata)
     {
         metadata.Remove(ServerVersionKey);

src/NATS.Server/JetStream/Models/CounterValue.cs

@@ -7,15 +7,32 @@ namespace NATS.Server.JetStream.Models;
 // Reference: golang/nats-server/server/stream.go:20759
 public sealed class CounterValue
 {
+    /// <summary>
+    /// Gets or sets the counter value encoded as a string for wire compatibility.
+    /// </summary>
     [JsonPropertyName("val")]
     public string Value { get; set; } = "0";
 
+    /// <summary>
+    /// Parses the string counter value as a signed 64-bit integer.
+    /// </summary>
     public long AsLong() => long.TryParse(Value, out var v) ? v : 0;
 
+    /// <summary>
+    /// Creates a counter payload object from a numeric value.
+    /// </summary>
+    /// <param name="value">Numeric counter value to encode.</param>
     public static CounterValue FromLong(long value) => new() { Value = value.ToString() };
 
+    /// <summary>
+    /// Serializes the counter payload to JSON UTF-8 bytes.
+    /// </summary>
     public byte[] ToPayload() => JsonSerializer.SerializeToUtf8Bytes(this);
 
+    /// <summary>
+    /// Deserializes a counter payload from JSON bytes.
+    /// </summary>
+    /// <param name="payload">JSON payload bytes containing the counter value.</param>
     public static CounterValue FromPayload(ReadOnlySpan<byte> payload)
     {
         if (payload.IsEmpty)

src/NATS.Server/JetStream/Models/StreamState.cs

@@ -2,8 +2,23 @@ namespace NATS.Server.JetStream.Models;
 
 public sealed class ApiStreamState
 {
+    /// <summary>
+    /// Gets or sets current number of messages stored in the stream.
+    /// </summary>
     public ulong Messages { get; set; }
+
+    /// <summary>
+    /// Gets or sets first available stream sequence.
+    /// </summary>
     public ulong FirstSeq { get; set; }
+
+    /// <summary>
+    /// Gets or sets latest stream sequence.
+    /// </summary>
     public ulong LastSeq { get; set; }
+
+    /// <summary>
+    /// Gets or sets total bytes retained by the stream.
+    /// </summary>
     public ulong Bytes { get; set; }
 }

src/NATS.Server/JetStream/Publish/JetStreamPubAckFormatter.cs

@@ -18,6 +18,9 @@ internal static class JetStreamPubAckFormatter
     /// Formats a success PubAck directly into a span. Returns bytes written.
     /// Caller must ensure dest is large enough (256 bytes is safe for any stream name).
     /// </summary>
+    /// <param name="dest">Destination span receiving UTF-8 formatted JSON bytes.</param>
+    /// <param name="streamName">Stream name included in the ack payload.</param>
+    /// <param name="seq">Assigned stream sequence to include in the ack payload.</param>
     public static int FormatSuccess(Span<byte> dest, string streamName, ulong seq)
     {
         var pos = 0;
@@ -36,6 +39,7 @@ internal static class JetStreamPubAckFormatter
     /// <summary>
     /// Returns true if this PubAck is a simple success that can use the fast formatter.
     /// </summary>
+    /// <param name="ack">Publish acknowledgement to classify.</param>
     public static bool IsSimpleSuccess(PubAck ack)
         => ack.ErrorCode == null && !ack.Duplicate && ack.BatchId == null;
 }

src/NATS.Server/JetStream/Publish/JetStreamPublisher.cs

@@ -9,17 +9,41 @@ public sealed class JetStreamPublisher
     // Go reference: server/jetstream_batching.go streamBatches
     private readonly AtomicBatchPublishEngine _batchEngine = new();
 
+    /// <summary>
+    /// Creates a JetStream publisher bound to a stream manager.
+    /// </summary>
+    /// <param name="streamManager">Stream manager used to resolve and capture published messages.</param>
     public JetStreamPublisher(StreamManager streamManager)
     {
         _streamManager = streamManager;
     }
 
+    /// <summary>
+    /// Captures a publish using default publish options.
+    /// </summary>
+    /// <param name="subject">Publish subject.</param>
+    /// <param name="payload">Message payload.</param>
+    /// <param name="ack">Publish acknowledgement output.</param>
     public bool TryCapture(string subject, ReadOnlyMemory<byte> payload, out PubAck ack)
         => TryCaptureWithOptions(subject, payload, new PublishOptions(), out ack);
 
+    /// <summary>
+    /// Captures a publish with an explicit message id for deduplication checks.
+    /// </summary>
+    /// <param name="subject">Publish subject.</param>
+    /// <param name="payload">Message payload.</param>
+    /// <param name="msgId">Optional message id used for duplicate detection.</param>
+    /// <param name="ack">Publish acknowledgement output.</param>
     public bool TryCapture(string subject, ReadOnlyMemory<byte> payload, string? msgId, out PubAck ack)
         => TryCaptureWithOptions(subject, payload, new PublishOptions { MsgId = msgId }, out ack);
 
+    /// <summary>
+    /// Captures a publish using explicit publish options and precondition checks.
+    /// </summary>
+    /// <param name="subject">Publish subject.</param>
+    /// <param name="payload">Message payload.</param>
+    /// <param name="options">Publish options including dedupe and expected-last preconditions.</param>
+    /// <param name="ack">Publish acknowledgement output.</param>
     public bool TryCaptureWithOptions(string subject, ReadOnlyMemory<byte> payload, PublishOptions options, out PubAck ack)
     {
         if (_streamManager.FindBySubject(subject) is not { } stream)

src/NATS.Server/JetStream/Publish/PubAck.cs

@@ -2,16 +2,37 @@ namespace NATS.Server.JetStream.Publish;
 
 public sealed class PubAck
 {
+    /// <summary>
+    /// Gets the stream name that accepted the published message.
+    /// </summary>
     public string Stream { get; init; } = string.Empty;
+
+    /// <summary>
+    /// Gets the stream sequence assigned to the accepted message.
+    /// </summary>
     public ulong Seq { get; init; }
+
+    /// <summary>
+    /// Gets a value indicating whether this acknowledgement represents a deduplicated publish.
+    /// </summary>
     public bool Duplicate { get; init; }
+
+    /// <summary>
+    /// Gets the JetStream API error code when the publish was rejected.
+    /// </summary>
     public int? ErrorCode { get; init; }
 
     // Go: JSPubAckResponse.BatchId — identifies which batch this ack belongs to.
     // Go reference: server/jetstream_batching.go (JSPubAckResponse struct)
+    /// <summary>
+    /// Gets the batch identifier when this ack belongs to an atomic publish batch.
+    /// </summary>
     public string? BatchId { get; init; }
 
     // Go: JSPubAckResponse.BatchSize — total number of messages committed in this batch.
     // Go reference: server/jetstream_batching.go (JSPubAckResponse struct)
+    /// <summary>
+    /// Gets the number of messages committed in the acknowledged batch.
+    /// </summary>
     public int BatchSize { get; init; }
 }

src/NATS.Server/JetStream/Publish/PublishOptions.cs

@@ -2,20 +2,47 @@ namespace NATS.Server.JetStream.Publish;
 
 public sealed class PublishOptions
 {
+    /// <summary>
+    /// Gets the idempotency token used to deduplicate retried publishes on the stream.
+    /// </summary>
     public string? MsgId { get; init; }
+
+    /// <summary>
+    /// Gets the expected stream last sequence precondition for optimistic concurrency checks.
+    /// </summary>
     public ulong ExpectedLastSeq { get; init; }
+
+    /// <summary>
+    /// Gets the expected last sequence for a specific subject when enforcing subject-level ordering.
+    /// </summary>
     public ulong ExpectedLastSubjectSeq { get; init; }
+
+    /// <summary>
+    /// Gets the subject associated with <see cref="ExpectedLastSubjectSeq"/> precondition checks.
+    /// </summary>
     public string? ExpectedLastSubjectSeqSubject { get; init; }
 
     // Go: Nats-Batch-Id header — identifies which atomic batch this message belongs to.
+    /// <summary>
+    /// Gets the batch identifier used to group staged messages into a single commit set.
+    /// </summary>
     public string? BatchId { get; init; }
 
     // Go: Nats-Batch-Sequence header — 1-based position within the batch.
+    /// <summary>
+    /// Gets the 1-based position of this message within its JetStream publish batch.
+    /// </summary>
     public ulong BatchSeq { get; init; }
 
     // Go: Nats-Batch-Commit header — "1" or "eob" to commit, null/empty to stage only.
+    /// <summary>
+    /// Gets the batch commit marker signaling end-of-batch or explicit commit behavior.
+    /// </summary>
     public string? BatchCommit { get; init; }
 
     // Go: Nats-Expected-Last-Msg-Id header — unsupported inside a batch.
+    /// <summary>
+    /// Gets the expected last message id precondition used to guard against duplicate writes.
+    /// </summary>
     public string? ExpectedLastMsgId { get; init; }
 }

src/NATS.Server/JetStream/Publish/PublishPreconditions.cs

@@ -6,6 +6,12 @@ public sealed class PublishPreconditions
 {
     private readonly ConcurrentDictionary<string, DedupeEntry> _dedupe = new(StringComparer.Ordinal);
 
+    /// <summary>
+    /// Checks whether a message id is still inside the duplicate window.
+    /// </summary>
+    /// <param name="msgId">Message-id header used for deduplication.</param>
+    /// <param name="duplicateWindowMs">Duplicate window size in milliseconds.</param>
+    /// <param name="existingSequence">Existing stored sequence when a duplicate is detected.</param>
     public bool IsDuplicate(string? msgId, int duplicateWindowMs, out ulong existingSequence)
     {
         existingSequence = 0;
@@ -26,6 +32,11 @@ public sealed class PublishPreconditions
         return true;
     }
 
+    /// <summary>
+    /// Records a message id and sequence for future duplicate detection.
+    /// </summary>
+    /// <param name="msgId">Message-id header value to track.</param>
+    /// <param name="sequence">Stream sequence assigned to the message.</param>
     public void Record(string? msgId, ulong sequence)
     {
         if (string.IsNullOrEmpty(msgId))
@@ -34,6 +45,10 @@ public sealed class PublishPreconditions
         _dedupe[msgId] = new DedupeEntry(sequence, DateTime.UtcNow);
     }
 
+    /// <summary>
+    /// Removes dedupe entries older than the duplicate window.
+    /// </summary>
+    /// <param name="duplicateWindowMs">Duplicate window size in milliseconds.</param>
     public void TrimOlderThan(int duplicateWindowMs)
     {
         if (duplicateWindowMs <= 0)
@@ -47,6 +62,11 @@ public sealed class PublishPreconditions
         }
     }
 
+    /// <summary>
+    /// Validates expected-last-sequence precondition against current stream sequence.
+    /// </summary>
+    /// <param name="expectedLastSeq">Expected last sequence from publish precondition header.</param>
+    /// <param name="actualLastSeq">Current stream last sequence.</param>
     public bool CheckExpectedLastSeq(ulong expectedLastSeq, ulong actualLastSeq)
         => expectedLastSeq == 0 || expectedLastSeq == actualLastSeq;
 

src/NATS.Server/JetStream/Storage/AeadEncryptor.cs

@@ -65,6 +65,9 @@ internal static class AeadEncryptor
     /// Encrypts <paramref name="plaintext"/> with the given <paramref name="cipher"/>
     /// and <paramref name="key"/>.
     /// </summary>
+    /// <param name="plaintext">Plain JetStream block bytes to protect at rest.</param>
+    /// <param name="key">32-byte encryption key derived for the store context.</param>
+    /// <param name="cipher">Configured at-rest cipher selection.</param>
     /// <returns>
     /// Wire format: <c>[12:nonce][16:tag][N:ciphertext]</c>
     /// </returns>
@@ -112,6 +115,9 @@ internal static class AeadEncryptor
     /// <summary>
     /// Decrypts data produced by <see cref="Encrypt"/>.
     /// </summary>
+    /// <param name="encrypted">Encrypted block bytes in nonce/tag/ciphertext wire format.</param>
+    /// <param name="key">32-byte encryption key used when the block was encrypted.</param>
+    /// <param name="cipher">Configured at-rest cipher selection.</param>
     /// <returns>Plaintext bytes.</returns>
     /// <exception cref="ArgumentException">If key length is not 32 bytes or data is too short.</exception>
     /// <exception cref="CryptographicException">If authentication tag verification fails.</exception>

src/NATS.Server/JetStream/Storage/AtomicFileWriter.cs

@@ -18,6 +18,8 @@ public static class AtomicFileWriter
     /// The data is written to a unique <c>{path}.{random}.tmp</c> sibling, flushed,
     /// then renamed over <paramref name="path"/> with overwrite semantics.
     /// </summary>
+    /// <param name="path">Target file path to replace atomically.</param>
+    /// <param name="data">Binary payload bytes to persist.</param>
     public static async Task WriteAtomicallyAsync(string path, byte[] data)
     {
         var tmpPath = path + "." + Path.GetRandomFileName() + ".tmp";
@@ -35,6 +37,8 @@ public static class AtomicFileWriter
     /// The data is written to a unique <c>{path}.{random}.tmp</c> sibling, flushed,
     /// then renamed over <paramref name="path"/> with overwrite semantics.
     /// </summary>
+    /// <param name="path">Target file path to replace atomically.</param>
+    /// <param name="data">Binary payload bytes to persist.</param>
     public static async Task WriteAtomicallyAsync(string path, ReadOnlyMemory<byte> data)
     {
         var tmpPath = path + "." + Path.GetRandomFileName() + ".tmp";

src/NATS.Server/JetStream/Storage/ConsumerState.cs

@@ -26,16 +26,28 @@ public record struct Pending(ulong Sequence, long Timestamp);
 public sealed class ConsumerState
 {
     // Go: ConsumerState.Delivered — highest consumer-seq and stream-seq delivered
+    /// <summary>
+    /// Gets or sets highest delivered consumer/stream sequence pair.
+    /// </summary>
     public SequencePair Delivered { get; set; }
 
     // Go: ConsumerState.AckFloor — highest consumer-seq and stream-seq fully acknowledged
+    /// <summary>
+    /// Gets or sets highest fully acknowledged consumer/stream sequence pair.
+    /// </summary>
     public SequencePair AckFloor { get; set; }
 
     // Go: ConsumerState.Pending — pending acks keyed by stream sequence; only present
     //     when AckPolicy is Explicit.
+    /// <summary>
+    /// Gets or sets pending explicit-ack entries keyed by stream sequence.
+    /// </summary>
     public Dictionary<ulong, Pending>? Pending { get; set; }
 
     // Go: ConsumerState.Redelivered — redelivery counts keyed by stream sequence;
     //     only present when a message has been delivered more than once.
+    /// <summary>
+    /// Gets or sets redelivery counters keyed by stream sequence.
+    /// </summary>
     public Dictionary<ulong, ulong>? Redelivered { get; set; }
 }

src/NATS.Server/JetStream/Storage/ConsumerStateCodec.cs

@@ -44,6 +44,7 @@ public static class ConsumerStateCodec
     /// Encodes consumer state into the Go-compatible binary format.
     /// Reference: golang/nats-server/server/store.go:397
     /// </summary>
+    /// <param name="state">Consumer state to serialize.</param>
     public static byte[] Encode(ConsumerState state)
     {
         // Upper-bound the buffer size.
@@ -105,6 +106,7 @@ public static class ConsumerStateCodec
     /// Decodes consumer state from the Go-compatible binary format.
     /// Reference: golang/nats-server/server/filestore.go:12216
     /// </summary>
+    /// <param name="buf">Binary payload bytes containing encoded consumer state.</param>
     public static ConsumerState Decode(ReadOnlySpan<byte> buf)
     {
         // Copy to array first so lambdas can capture without ref-type restrictions.

src/NATS.Server/JetStream/Storage/FileStoreBlock.cs

@@ -2,9 +2,28 @@ namespace NATS.Server.JetStream.Storage;
 
 public sealed class FileStoreBlock
 {
+    /// <summary>
+    /// Gets the logical block identifier within the stream file-store layout.
+    /// </summary>
     public int Id { get; init; }
+
+    /// <summary>
+    /// Gets the filesystem path to the backing block file.
+    /// </summary>
     public required string Path { get; init; }
+
+    /// <summary>
+    /// Gets the first stream sequence represented by this block.
+    /// </summary>
     public ulong Sequence { get; init; }
+
+    /// <summary>
+    /// Gets the byte offset of this block relative to stream storage bookkeeping.
+    /// </summary>
     public long OffsetBytes { get; init; }
+
+    /// <summary>
+    /// Gets or sets the current block size in bytes.
+    /// </summary>
     public long SizeBytes { get; set; }
 }

src/NATS.Server/JetStream/Storage/FileStoreConfig.cs

@@ -11,35 +11,50 @@ namespace NATS.Server.JetStream.Storage;
 /// </summary>
 public sealed class FileStoreConfig
 {
-    // Go: FileStoreConfig.StoreDir — root directory for all stream block files
+    /// <summary>
+    /// Gets or sets the root directory used to persist JetStream stream and consumer state on disk.
+    /// </summary>
     public string StoreDir { get; set; } = string.Empty;
 
-    // Go: FileStoreConfig.BlockSize — maximum bytes per message block file.
+    /// <summary>
-    //     0 means use the engine default (currently 8 MiB in Go).
+    /// Gets or sets the maximum size of each JetStream message block file in bytes.
+    /// Use <c>0</c> to apply the server default block size.
+    /// </summary>
     public ulong BlockSize { get; set; }
 
-    // Go: FileStoreConfig.CacheExpire — how long to keep a loaded block in memory
+    /// <summary>
-    //     after the last read before evicting. Default: 10 seconds.
+    /// Gets or sets how long a loaded block stays in memory after last access before eviction.
+    /// </summary>
     public TimeSpan CacheExpire { get; set; } = TimeSpan.FromSeconds(10);
 
-    // Go: FileStoreConfig.SubjectStateExpire — how long to keep per-subject state cached
+    /// <summary>
-    //     on an idle message block. Zero means use CacheExpire.
+    /// Gets or sets how long per-subject accounting metadata remains cached for idle blocks.
+    /// When set to <see cref="TimeSpan.Zero"/>, <see cref="CacheExpire"/> is used.
+    /// </summary>
     public TimeSpan SubjectStateExpire { get; set; }
 
-    // Go: FileStoreConfig.SyncInterval — interval at which dirty blocks are fsynced.
+    /// <summary>
-    //     Default: 2 minutes.
+    /// Gets or sets how frequently dirty file-store blocks are synchronized to durable storage.
+    /// </summary>
     public TimeSpan SyncInterval { get; set; } = TimeSpan.FromMinutes(2);
 
-    // Go: FileStoreConfig.SyncAlways — when true every write is immediately fsynced
+    /// <summary>
+    /// Gets or sets a value indicating whether each write is immediately synced for maximum durability.
+    /// </summary>
     public bool SyncAlways { get; set; }
 
-    // Go: FileStoreConfig.AsyncFlush — when true write operations are batched and
+    /// <summary>
-    //     flushed asynchronously for higher throughput
+    /// Gets or sets a value indicating whether flushes are performed asynchronously to improve throughput.
+    /// </summary>
     public bool AsyncFlush { get; set; }
 
-    // Go: FileStoreConfig.Cipher — cipher used for at-rest encryption; NoCipher disables it
+    /// <summary>
+    /// Gets or sets the encryption mode used for JetStream data at rest.
+    /// </summary>
     public StoreCipher Cipher { get; set; } = StoreCipher.NoCipher;
 
-    // Go: FileStoreConfig.Compression — compression algorithm applied to block data
+    /// <summary>
+    /// Gets or sets the compression mode applied to persisted JetStream block payloads.
+    /// </summary>
     public StoreCompression Compression { get; set; } = StoreCompression.NoCompression;
 }

src/NATS.Server/JetStream/Validation/JetStreamConfigValidator.cs

@@ -7,6 +7,10 @@ namespace NATS.Server.JetStream.Validation;
 
 public static class JetStreamConfigValidator
 {
+    /// <summary>
+    /// Validates stream/consumer names against JetStream naming constraints.
+    /// </summary>
+    /// <param name="name">Candidate name string.</param>
     public static bool IsValidName(string? name)
     {
         if (string.IsNullOrWhiteSpace(name))
@@ -25,9 +29,17 @@ public static class JetStreamConfigValidator
         return true;
     }
 
+    /// <summary>
+    /// Returns true when metadata key/value bytes are within JetStream size limits.
+    /// </summary>
+    /// <param name="metadata">Metadata dictionary to measure.</param>
     public static bool IsMetadataWithinLimit(Dictionary<string, string>? metadata)
         => MetadataByteSize(metadata) <= JetStreamApiLimits.JSMaxMetadataLen;
 
+    /// <summary>
+    /// Computes UTF-8 byte size for all metadata keys and values.
+    /// </summary>
+    /// <param name="metadata">Metadata dictionary to measure.</param>
     public static int MetadataByteSize(Dictionary<string, string>? metadata)
     {
         if (metadata is null || metadata.Count == 0)
@@ -43,6 +55,10 @@ public static class JetStreamConfigValidator
         return size;
     }
 
+    /// <summary>
+    /// Validates a stream configuration for required fields and basic limit semantics.
+    /// </summary>
+    /// <param name="config">Stream configuration to validate.</param>
     public static ValidationResult Validate(StreamConfig config)
     {
         if (string.IsNullOrWhiteSpace(config.Name) || config.Subjects.Count == 0)
@@ -66,6 +82,7 @@ public static class JetStreamConfigValidator
     /// both server_name and cluster.name must be set.
     /// Reference: Go server/jetstream.go validateOptions (line ~2822-2831).
     /// </summary>
+    /// <param name="options">Server options containing JetStream and cluster settings.</param>
     public static ValidationResult ValidateClusterConfig(NatsOptions options)
     {
         // If JetStream is not enabled or not clustered, no cluster-specific checks needed.
@@ -84,7 +101,9 @@ public static class JetStreamConfigValidator
 
 public sealed class ValidationResult
 {
+    /// <summary>Indicates whether validation succeeded.</summary>
     public bool IsValid { get; }
+    /// <summary>Validation error message when <see cref="IsValid"/> is false.</summary>
     public string Message { get; }
 
     private ValidationResult(bool isValid, string message)
@@ -93,6 +112,9 @@ public sealed class ValidationResult
         Message = message;
     }
 
+    /// <summary>Creates a successful validation result.</summary>
     public static ValidationResult Valid() => new(true, string.Empty);
+    /// <summary>Creates a failed validation result with an explanatory message.</summary>
+    /// <param name="message">Validation failure reason.</param>
     public static ValidationResult Invalid(string message) => new(false, message);
 }

src/NATS.Server/LeafNodes/LeafConnectInfo.cs

@@ -8,33 +8,43 @@ namespace NATS.Server.LeafNodes;
 /// </summary>
 public sealed class LeafConnectInfo
 {
+    /// <summary>Optional user JWT presented during leaf authentication.</summary>
     [JsonPropertyName("jwt")]
     public string? Jwt { get; init; }
 
+    /// <summary>Client public NKey used for nonce-signature authentication.</summary>
     [JsonPropertyName("nkey")]
     public string? Nkey { get; init; }
 
+    /// <summary>Nonce signature proving ownership of <see cref="Nkey"/>.</summary>
     [JsonPropertyName("sig")]
     public string? Sig { get; init; }
 
+    /// <summary>Whether this leaf connection advertises hub mode support.</summary>
     [JsonPropertyName("hub")]
     public bool Hub { get; init; }
 
+    /// <summary>Optional cluster name associated with the remote leaf node.</summary>
     [JsonPropertyName("cluster")]
     public string? Cluster { get; init; }
 
+    /// <summary>Whether protocol headers are supported on this leaf connection.</summary>
     [JsonPropertyName("headers")]
     public bool Headers { get; init; }
 
+    /// <summary>Whether JetStream asset and API forwarding are supported.</summary>
     [JsonPropertyName("jetstream")]
     public bool JetStream { get; init; }
 
+    /// <summary>Negotiated compression mode for leaf traffic.</summary>
     [JsonPropertyName("compression")]
     public string? Compression { get; init; }
 
+    /// <summary>Optional remote account binding for this solicited leaf link.</summary>
     [JsonPropertyName("remote_account")]
     public string? RemoteAccount { get; init; }
 
+    /// <summary>Leaf protocol version number.</summary>
     [JsonPropertyName("proto")]
     public int Proto { get; init; }
 }

src/NATS.Server/LeafNodes/LeafHubSpokeMapper.cs

@@ -32,6 +32,10 @@ public sealed class LeafHubSpokeMapper
     private readonly IReadOnlyList<string> _allowExports;
     private readonly IReadOnlyList<string> _allowImports;
 
+    /// <summary>
+    /// Creates a mapper with account mapping only (no subject allow/deny filters).
+    /// </summary>
+    /// <param name="hubToSpoke">Mapping from hub account names to spoke account names.</param>
     public LeafHubSpokeMapper(IReadOnlyDictionary<string, string> hubToSpoke)
         : this(hubToSpoke, [], [], [], [])
     {
@@ -40,6 +44,9 @@ public sealed class LeafHubSpokeMapper
     /// <summary>
     /// Creates a mapper with account mapping and subject deny filters (legacy constructor).
     /// </summary>
+    /// <param name="hubToSpoke">Mapping from hub account names to spoke account names.</param>
+    /// <param name="denyExports">Subject patterns denied for hub→leaf flow.</param>
+    /// <param name="denyImports">Subject patterns denied for leaf→hub flow.</param>
     public LeafHubSpokeMapper(
         IReadOnlyDictionary<string, string> hubToSpoke,
         IReadOnlyList<string> denyExports,
@@ -74,6 +81,9 @@ public sealed class LeafHubSpokeMapper
     /// <summary>
     /// Maps an account from hub→spoke or spoke→hub based on direction.
     /// </summary>
+    /// <param name="account">Account name to map.</param>
+    /// <param name="subject">Subject associated with the mapping request.</param>
+    /// <param name="direction">Flow direction determining which map to apply.</param>
     public LeafMappingResult Map(string account, string subject, LeafMapDirection direction)
     {
         if (direction == LeafMapDirection.Outbound && _hubToSpoke.TryGetValue(account, out var spoke))
@@ -89,6 +99,8 @@ public sealed class LeafHubSpokeMapper
     /// When an allow-list is set, the subject must also match at least one allow pattern.
     /// Deny takes precedence over allow (Go reference: auth.go SubjectPermission semantics).
     /// </summary>
+    /// <param name="subject">Subject to evaluate.</param>
+    /// <param name="direction">Flow direction used to choose allow/deny lists.</param>
     public bool IsSubjectAllowed(string subject, LeafMapDirection direction)
     {
         var (denyList, allowList) = direction switch

src/NATS.Server/LeafNodes/LeafLoopDetector.cs

@@ -4,15 +4,34 @@ public static class LeafLoopDetector
 {
     private const string LeafLoopPrefix = "$LDS.";
 
+    /// <summary>
+    /// Determines whether a subject contains the leaf-loop marker prefix.
+    /// </summary>
+    /// <param name="subject">Subject to inspect for loop marker metadata.</param>
     public static bool HasLoopMarker(string subject)
         => subject.StartsWith(LeafLoopPrefix, StringComparison.Ordinal);
 
+    /// <summary>
+    /// Prefixes a subject with local loop-detection metadata for leaf forwarding.
+    /// </summary>
+    /// <param name="subject">Original subject being forwarded.</param>
+    /// <param name="serverId">Server identifier appended to the loop marker.</param>
     public static string Mark(string subject, string serverId)
         => $"{LeafLoopPrefix}{serverId}.{subject}";
 
+    /// <summary>
+    /// Determines whether the subject indicates a loop back to the local server.
+    /// </summary>
+    /// <param name="subject">Forwarded subject containing loop markers.</param>
+    /// <param name="localServerId">Current server identifier.</param>
     public static bool IsLooped(string subject, string localServerId)
         => subject.StartsWith($"{LeafLoopPrefix}{localServerId}.", StringComparison.Ordinal);
 
+    /// <summary>
+    /// Removes all loop markers from a subject and returns the unmarked subject.
+    /// </summary>
+    /// <param name="subject">Subject that may contain one or more loop markers.</param>
+    /// <param name="unmarked">Unmarked subject when removal succeeds.</param>
     public static bool TryUnmark(string subject, out string unmarked)
     {
         unmarked = subject;

src/NATS.Server/LeafNodes/LeafSubKey.cs

@@ -16,6 +16,10 @@ public static class LeafSubKey
     public static readonly TimeSpan SharedSysAccDelay = TimeSpan.FromMilliseconds(250);
     public static readonly TimeSpan ConnectProcessTimeout = TimeSpan.FromSeconds(2);
 
+    /// <summary>
+    /// Builds canonical subscription key from subject and optional queue group.
+    /// </summary>
+    /// <param name="sub">Subscription used to build key components.</param>
     public static string KeyFromSub(Subscription sub)
     {
         ArgumentNullException.ThrowIfNull(sub);
@@ -24,6 +28,11 @@ public static class LeafSubKey
             : sub.Subject;
     }
 
+    /// <summary>
+    /// Builds canonical subscription key including routed-origin metadata when present.
+    /// </summary>
+    /// <param name="sub">Subscription used to build key components.</param>
+    /// <param name="origin">Optional routed origin identifier.</param>
     public static string KeyFromSubWithOrigin(Subscription sub, string? origin = null)
     {
         ArgumentNullException.ThrowIfNull(sub);

src/NATS.Server/LeafNodes/WebSocketStreamAdapter.cs

@@ -17,6 +17,11 @@ public sealed class WebSocketStreamAdapter : Stream
     private int _readCount;
     private bool _disposed;
 
+    /// <summary>
+    /// Creates a stream adapter for a WebSocket-backed leaf-node transport.
+    /// </summary>
+    /// <param name="ws">WebSocket transport used for framed binary I/O.</param>
+    /// <param name="initialBufferSize">Initial receive staging-buffer size.</param>
     public WebSocketStreamAdapter(SystemWebSocket ws, int initialBufferSize = 4096)
     {
         _ws = ws ?? throw new ArgumentNullException(nameof(ws));
@@ -34,10 +39,15 @@ public sealed class WebSocketStreamAdapter : Stream
     public override bool CanSeek => false;
 
     // Telemetry properties
+    /// <summary>Whether the underlying WebSocket is currently open.</summary>
     public bool IsConnected => _ws.State == WebSocketState.Open;
+    /// <summary>Total bytes read from received WebSocket messages.</summary>
     public long BytesRead { get; private set; }
+    /// <summary>Total bytes written to outbound WebSocket messages.</summary>
     public long BytesWritten { get; private set; }
+    /// <summary>Total completed WebSocket messages read.</summary>
     public int MessagesRead { get; private set; }
+    /// <summary>Total completed WebSocket messages written.</summary>
     public int MessagesWritten { get; private set; }
 
     /// <inheritdoc />
@@ -196,12 +206,18 @@ public sealed class WebSocketStreamAdapter : Stream
         get => throw new NotSupportedException();
         set => throw new NotSupportedException();
     }
+    /// <inheritdoc />
     public override long Seek(long offset, SeekOrigin origin) => throw new NotSupportedException();
+    /// <inheritdoc />
     public override void SetLength(long value) => throw new NotSupportedException();
+    /// <inheritdoc />
     public override int Read(byte[] buffer, int offset, int count) => throw new NotSupportedException("Use async methods");
+    /// <inheritdoc />
     public override void Write(byte[] buffer, int offset, int count) => throw new NotSupportedException("Use async methods");
+    /// <inheritdoc />
     public override void Flush() { }
 
+    /// <inheritdoc />
     protected override void Dispose(bool disposing)
     {
         if (_disposed)

src/NATS.Server/Monitoring/AccountzHandler.cs

@@ -6,11 +6,18 @@ public sealed class AccountzHandler
 {
     private readonly NatsServer _server;
 
+    /// <summary>
+    /// Creates handler for account-focused monitoring endpoints.
+    /// </summary>
+    /// <param name="server">Server instance providing account snapshots.</param>
     public AccountzHandler(NatsServer server)
     {
         _server = server;
     }
 
+    /// <summary>
+    /// Builds account overview payload for <c>/accountz</c>.
+    /// </summary>
     public object Build()
     {
         var accounts = _server.GetAccounts().Select(ToAccountDto).ToArray();
@@ -21,6 +28,9 @@ public sealed class AccountzHandler
         };
     }
 
+    /// <summary>
+    /// Builds aggregate account statistics payload for <c>/accstatz</c>.
+    /// </summary>
     public object BuildStats()
     {
         var accounts = _server.GetAccounts().ToArray();

src/NATS.Server/Monitoring/ClosedConnectionRingBuffer.cs

@@ -13,19 +13,32 @@ public sealed class ClosedConnectionRingBuffer
     private int _count;       // Current count (up to capacity)
     private long _totalClosed; // Running total of all closed connections ever
 
+    /// <summary>
+    /// Creates a fixed-size closed-connection ring buffer.
+    /// </summary>
+    /// <param name="capacity">Maximum number of recent closed-client snapshots retained.</param>
     public ClosedConnectionRingBuffer(int capacity = 1024)
     {
         if (capacity <= 0) throw new ArgumentOutOfRangeException(nameof(capacity), "Capacity must be greater than zero.");
         _buffer = new ClosedClient[capacity];
     }
 
+    /// <summary>
+    /// Gets the maximum number of closed-client entries retained before wraparound.
+    /// </summary>
     public int Capacity => _buffer.Length;
 
+    /// <summary>
+    /// Gets the number of currently retained closed-client entries.
+    /// </summary>
     public int Count
     {
         get { lock (_lock) return _count; }
     }
 
+    /// <summary>
+    /// Gets the lifetime total count of closed connections observed by this buffer.
+    /// </summary>
     public long TotalClosed
     {
         get { lock (_lock) return _totalClosed; }
@@ -34,6 +47,7 @@ public sealed class ClosedConnectionRingBuffer
     /// <summary>
     /// Adds a closed connection snapshot. If the buffer is full the oldest entry is overwritten.
     /// </summary>
+    /// <param name="info">Closed-client snapshot to append into the ring.</param>
     public void Add(ClosedClient info)
     {
         lock (_lock)
@@ -60,6 +74,7 @@ public sealed class ClosedConnectionRingBuffer
     /// <summary>
     /// Returns up to <paramref name="count"/> most recent entries, ordered newest-first.
     /// </summary>
+    /// <param name="count">Maximum number of recent entries to return.</param>
     public IReadOnlyList<ClosedClient> GetRecent(int count)
     {
         lock (_lock)

src/NATS.Server/Monitoring/GatewayzHandler.cs

@@ -4,11 +4,18 @@ public sealed class GatewayzHandler
 {
     private readonly NatsServer _server;
 
+    /// <summary>
+    /// Creates gateway monitoring handler.
+    /// </summary>
+    /// <param name="server">Server instance providing gateway metrics.</param>
     public GatewayzHandler(NatsServer server)
     {
         _server = server;
     }
 
+    /// <summary>
+    /// Builds gateway metrics payload for <c>/gatewayz</c>.
+    /// </summary>
     public object Build()
     {
         var gateways = _server.Stats.Gateways;

src/NATS.Server/Monitoring/Healthz.cs

@@ -8,18 +8,33 @@ namespace NATS.Server.Monitoring;
 /// </summary>
 public sealed class HealthStatus
 {
+    /// <summary>
+    /// Gets the overall health status string returned by the monitoring endpoint.
+    /// </summary>
     [JsonPropertyName("status")]
     public string Status { get; init; } = "ok";
 
+    /// <summary>
+    /// Gets the HTTP-style status code representing current server health.
+    /// </summary>
     [JsonPropertyName("status_code")]
     public int StatusCode { get; init; } = 200;
 
+    /// <summary>
+    /// Gets the top-level error message when health checks fail.
+    /// </summary>
     [JsonPropertyName("error")]
     public string? Error { get; init; }
 
+    /// <summary>
+    /// Gets detailed health-check failures contributing to a non-OK status.
+    /// </summary>
     [JsonPropertyName("errors")]
     public HealthzError[] Errors { get; init; } = [];
 
+    /// <summary>
+    /// Creates a successful health response payload used by <c>/healthz</c>.
+    /// </summary>
     public static HealthStatus Ok() => new();
 }
 
@@ -29,9 +44,15 @@ public sealed class HealthStatus
 /// </summary>
 public sealed class HealthzError
 {
+    /// <summary>
+    /// Gets the subsystem classification for this health failure.
+    /// </summary>
     [JsonPropertyName("type")]
     public HealthzErrorType Type { get; init; } = HealthzErrorType.Unknown;
 
+    /// <summary>
+    /// Gets the subsystem-specific failure detail emitted for diagnostics.
+    /// </summary>
     [JsonPropertyName("error")]
     public string Error { get; init; } = string.Empty;
 }

src/NATS.Server/Monitoring/JszHandler.cs

@@ -7,12 +7,20 @@ public sealed class JszHandler
     private readonly NatsServer _server;
     private readonly NatsOptions _options;
 
+    /// <summary>
+    /// Creates a JetStream monitoring response builder bound to server runtime state.
+    /// </summary>
+    /// <param name="server">Running server instance exposing JetStream counters and IDs.</param>
+    /// <param name="options">Server options containing JetStream capacity configuration.</param>
     public JszHandler(NatsServer server, NatsOptions options)
     {
         _server = server;
         _options = options;
     }
 
+    /// <summary>
+    /// Builds a point-in-time <c>/jsz</c> style response from current server state.
+    /// </summary>
     public JszResponse Build()
     {
         return new JszResponse
@@ -38,33 +46,43 @@ public sealed class JszHandler
 
 public sealed class JszResponse
 {
+    /// <summary>Server identifier for the node producing this response.</summary>
     [JsonPropertyName("server_id")]
     public string ServerId { get; set; } = string.Empty;
 
+    /// <summary>UTC timestamp when this monitoring snapshot was generated.</summary>
     [JsonPropertyName("now")]
     public DateTime Now { get; set; }
 
+    /// <summary>Whether JetStream is enabled on this server.</summary>
     [JsonPropertyName("enabled")]
     public bool Enabled { get; set; }
 
+    /// <summary>JetStream memory usage in bytes.</summary>
     [JsonPropertyName("memory")]
     public ulong Memory { get; set; }
 
+    /// <summary>JetStream file-storage usage in bytes.</summary>
     [JsonPropertyName("storage")]
     public ulong Storage { get; set; }
 
+    /// <summary>Number of JetStream streams currently hosted.</summary>
     [JsonPropertyName("streams")]
     public int Streams { get; set; }
 
+    /// <summary>Number of JetStream consumers currently hosted.</summary>
     [JsonPropertyName("consumers")]
     public int Consumers { get; set; }
 
+    /// <summary>Total number of JetStream API requests handled.</summary>
     [JsonPropertyName("api_total")]
     public ulong ApiTotal { get; set; }
 
+    /// <summary>Total number of JetStream API requests that returned errors.</summary>
     [JsonPropertyName("api_errors")]
     public ulong ApiErrors { get; set; }
 
+    /// <summary>Configured JetStream resource limits and storage directory.</summary>
     [JsonPropertyName("config")]
     public JetStreamConfig Config { get; set; } = new();
 }

src/NATS.Server/Monitoring/LeafzHandler.cs

@@ -4,11 +4,18 @@ public sealed class LeafzHandler
 {
     private readonly NatsServer _server;
 
+    /// <summary>
+    /// Creates leaf-node monitoring handler.
+    /// </summary>
+    /// <param name="server">Server instance providing leaf metrics.</param>
     public LeafzHandler(NatsServer server)
     {
         _server = server;
     }
 
+    /// <summary>
+    /// Builds leaf-node metrics payload for <c>/leafz</c>.
+    /// </summary>
     public object Build()
     {
         var leafs = _server.Stats.Leafs;

src/NATS.Server/Monitoring/MonitorServer.cs

@@ -23,6 +23,13 @@ public sealed class MonitorServer : IAsyncDisposable
     private readonly AccountzHandler _accountzHandler;
     private readonly PprofHandler _pprofHandler;
 
+    /// <summary>
+    /// Creates monitoring HTTP server wiring and endpoint handlers.
+    /// </summary>
+    /// <param name="server">Server runtime state used by monitoring handlers.</param>
+    /// <param name="options">Monitoring and feature options controlling endpoint behavior.</param>
+    /// <param name="stats">Shared HTTP request stats counters.</param>
+    /// <param name="loggerFactory">Logger factory for monitor diagnostics.</param>
     public MonitorServer(NatsServer server, NatsOptions options, ServerStats stats, ILoggerFactory loggerFactory)
     {
         _logger = loggerFactory.CreateLogger<MonitorServer>();
@@ -137,12 +144,19 @@ public sealed class MonitorServer : IAsyncDisposable
         }
     }
 
+    /// <summary>
+    /// Starts the monitoring web server.
+    /// </summary>
+    /// <param name="ct">Cancellation token for server startup.</param>
     public async Task StartAsync(CancellationToken ct)
     {
         await _app.StartAsync(ct);
         _logger.LogInformation("Monitoring listening on {Urls}", string.Join(", ", _app.Urls));
     }
 
+    /// <summary>
+    /// Stops and disposes monitoring server resources.
+    /// </summary>
     public async ValueTask DisposeAsync()
     {
         await _app.StopAsync();

src/NATS.Server/Monitoring/PprofHandler.cs

@@ -8,6 +8,9 @@ namespace NATS.Server.Monitoring;
 /// </summary>
 public sealed class PprofHandler
 {
+    /// <summary>
+    /// Returns index content for pprof-compatible endpoint listing.
+    /// </summary>
     public string Index()
     {
         return """
@@ -21,6 +24,10 @@ public sealed class PprofHandler
                """;
     }
 
+    /// <summary>
+    /// Captures lightweight CPU profile metadata payload.
+    /// </summary>
+    /// <param name="seconds">Requested capture duration in seconds.</param>
     public byte[] CaptureCpuProfile(int seconds)
     {
         var boundedSeconds = Math.Clamp(seconds, 1, 120);

src/NATS.Server/Monitoring/RoutezHandler.cs

@@ -4,11 +4,18 @@ public sealed class RoutezHandler
 {
     private readonly NatsServer _server;
 
+    /// <summary>
+    /// Creates route monitoring handler.
+    /// </summary>
+    /// <param name="server">Server instance providing route metrics.</param>
     public RoutezHandler(NatsServer server)
     {
         _server = server;
     }
 
+    /// <summary>
+    /// Builds route metrics payload for <c>/routez</c>.
+    /// </summary>
     public object Build()
     {
         var routes = _server.Stats.Routes;