Support drain-on-dispose for PCGroups consumers

[colprog]

Attempt to fix #65

Upgrade NATS.Net to 2.8.0 and let static and elastic PCGroups consume loops complete when the underlying JetStream consumer finishes during drain-on-dispose.

Add regression coverage for buffered-message drain behavior on connection disposal and document the graceful shutdown option.

[synadia-claude-reviewer]

Claude finished @colprog's task in 7m 30s —— View job

---

PR Review: Support drain-on-dispose for PCGroups consumers

• Gather context (CLAUDE.md, PR diff)
• Review static/elastic consume context changes
• Review test coverage
• Review documentation changes
• Post inline comments for specific issues
• Post overall review summary

---

Summary

The approach is correct. When nats.DisposeAsync() triggers drain, NATS.Net 2.8.0 completes the ConsumeAsync enumerable cleanly (hasNext == false) rather than throwing. Without the fix the outer loop restarts consume, hitting errors during connection teardown. The yield break terminates the iterator, the extension method's finally then calls context.DisposeAsync() and the watch task is cancelled cleanly. End-to-end lifecycle is sound.

Issues found

Medium — implicit NATS.Net contract (both contexts)

_js.Connection.Opts.DrainSubscriptionsOnDispose is a static option used as a runtime proxy for "drain is in progress". This is only safe if NATS.Net guarantees that ConsumeAsync never completes with false during ordinary fetch-window expiration when this option is set — only during drain. If that invariant ever changes, consumers configured with DrainSubscriptionsOnDispose = true would silently stop after the first fetch round. The assumption is reasonable given the 2.8.0 behaviour, but it isn't documented. See inline comments on NatsPcgElasticConsumeContext.cs:226 and NatsPcgStaticConsumeContext.cs:181.

Low — test resource leak (both test files)

nats is not await using (intentionally, to test manual disposal), but it is also not disposed in the finally block. If AssertCompletesWithinAsync(reachedBail.Task, ...) times out before nats.DisposeAsync() is reached, the connection leaks for the test run. Adding await nats.DisposeAsync() to the finally block is the minimal fix. See inline comments on NatsPcgElasticExtensionsTests.cs:779 and NatsPcgStaticExtensionsTests.cs:631.

No other issues

• The NATS.Net version bump (preview.2 → 2.8.0) is straightforward.
• TaskTestHelpers.AssertCompletesWithinAsync is implemented correctly (ReferenceEquals identity check, exception re-thrown from the original task).
• Documentation in PACKAGE.md is accurate and well-placed.
• The yield break vs break distinction is correct: break exits to the outer restart loop while yield break terminates the whole iterator, which is exactly what drain requires.
• The extension method's finally (context.DisposeAsync()) ensures the KV watch task is cancelled cleanly after the drain path exits, so there is no watch-task leak.

[mtmk]

LGTM thanks @colprog