Add TermWithReason support to AckTerminateAsync

[mtmk]

Add optional reason parameter to AckTerminateAsync that sends +TERM <reason> to the server, matching the Go client's TermWithReason functionality.

The reason appears in JetStream advisory events (requires NATS Server 2.10.4+).

Low-allocation implementation using ArrayPool<byte> with platform-specific optimizations for netstandard2.0 vs newer targets.

⚠️ This is a breaking change for applications implementing INatsJSMsg<T>

I only expect tests would break and can be detected and fairly easily fixed during build. However, if applications are using their own implementations of INatsJSMsg<T> they will break during build too but more severely if they are transitive dependencies using an earlier version of NATS.Client.JetStream they would fail at runtime.

Interface INatsJSMsg<T> Changes

Change	Binary Compatible	Source Compatible
default → null on ReplyAsync params	✅ Yes	✅ Yes
default → null on AckAsync param	✅ Yes	✅ Yes
default → null on NakAsync param	✅ Yes	✅ Yes
default → null on AckProgressAsync param	✅ Yes	✅ Yes
default → null on AckTerminateAsync param	✅ Yes	✅ Yes
New method AckTerminateAsync(string reason, ...)	❌ No	❌ No

---

Struct NatsJSMsg<T> Changes

Change	Binary Compatible	Source Compatible
default → null on all method params	✅ Yes	✅ Yes
New overload AckTerminateAsync(string reason, ...)	✅ Yes	✅ Yes
delay == default → delay == TimeSpan.Zero	✅ Yes	✅ Yes
Connection == default → Connection == null	✅ Yes	✅ Yes
Doc comments → <inheritdoc />	✅ Yes	✅ Yes
Internal NatsJSMsgConstants class	✅ Yes	✅ Yes

---

Final Verdict

Usage Pattern	Safe to Ship?
Applications using NatsJSMsg<T> directly	✅ Yes
Applications calling methods via INatsJSMsg<T>	✅ Yes
Applications/libraries implementing INatsJSMsg<T>	❌ No

---

Breaking Change Details

What breaks:

// Any type implementing INatsJSMsg<T> - e.g., user mocks for testing
public class MockJSMsg<T> : INatsJSMsg<T>
{
    // Must now implement:
    // ValueTask AckTerminateAsync(string reason, AckOpts? opts, CancellationToken ct)
}

How it breaks:

Scenario: Source break
Failure Mode: Compilation error when updating package and recompiling

Scenario: Binary break
Failure Mode: TypeLoadException at runtime if old compiled mock is loaded with new library version (transitive dependency scenario)

Who is affected:

• Users who created test doubles/mocks of INatsJSMsg
• Libraries that expose their own implementations of INatsJSMsg

Who is NOT affected:

• Users who only consume messages (vast majority)
• Users who only use the concrete NatsJSMsg struct

---

Risk Assessment

Factor: Likelihood of user interface implementations
Assessment: Medium - Interface docs explicitly mention "creating test doubles in unit testing"

Factor: Severity of break
Assessment: High - TypeLoadException crashes app at startup

Factor: Detectability
Assessment: Low for transitive - User may not know they have a dependency with an implementation

Factor: SemVer classification
Assessment: Breaking change - requires major version bump per SemVer

---

Conclusion

The current implementation is a breaking change.

It will cause TypeLoadException at runtime for any code that implements INatsJSMsg, including through transitive dependency updates where the user never modified their own code.

[scottf]

LGTM

[mtmk]

Alternative non breaking change using extension method:

  public static class NatsJSMsgExtensions
  {
      public static ValueTask AckTerminateAsync<T>(
          this NatsJSMsg<T> msg,
          string reason,
          AckOpts? opts = null,
          CancellationToken cancellationToken = default)
      {
          return msg.AckTerminateInternalAsync(reason, opts, cancellationToken);
      }
  }

Down side not useful for testing

[mtmk]

we can probably take the risk of breaking INatsJSMsg<T> in this occasion.