Document SignalR stateful reconnect in spec docs

[BrennanConroy]

Why

Issue #53103 points out that src/SignalR/docs/specs/TransportProtocols.md is out of date with respect to the stateful reconnect feature: it names the negotiate property useAck, but the shipped wire name is useStatefulReconnect, and it links to a literal [ack protocol](#todo) placeholder section that was never written. HubProtocol.md already had the wire formats for the Ack and Sequence messages, but no description of when/why they are exchanged or how sequence IDs and replay actually work.

What changed

TransportProtocols.md

• Renamed the negotiate query-string / response property from useAck to useStatefulReconnect to match NegotiateProtocol.cs and HttpConnectionDispatcher.cs.
• Replaced the dead [ack protocol](#todo) link with a real Stateful Reconnect section: opt-in handshake, WebSockets-only scope, and the reconnect flow (client reuses connectionToken on a new WebSocket, server reattaches instead of returning 409 Conflict, 404 if the connection has already been cleaned up).
• Updated the WebSockets transport section to note that the "no second WebSocket" 409 Conflict rule is relaxed for stateful-reconnect reattach.
• Scoped the transport's contract to reattach + notify the upper layer; explicitly defers buffering/ack/replay to upper layers, with the Hub protocol as a non-normative example.

HubProtocol.md

• Added cross-references from the existing Ack / Sequence rows in the message-summary table to the new semantics section.
• Added a Stateful Reconnect section that, after verifying against src/SignalR/common/Shared/MessageBuffer.cs, documents:
  • The trackable message set: HubInvocationMessage subtypes only (Invocation, StreamInvocation, StreamItem, Completion, CancelInvocation); Ping, Close, Ack, Sequence and handshakes are not tracked.
  • Per-direction 1-based sequence IDs that are not reset by a reconnect.
  • The duplicate-discard rule.
  • Periodic Ack semantics, including that a later Ack supersedes earlier ones for the same direction.
  • The Sequence-first reconnect handshake: sequenceId is highest_sent + 1, and the message is sent even when there are no buffered messages to replay so the peer knows where IDs continue.
• Kept the section transport-agnostic; TransportProtocols.md is mentioned only as an example transport binding.

Fixes #53103

Notes for reviewers

• Docs-only change. No code is modified.

[Copilot]

Pull request overview

Updates the SignalR spec documentation to reflect the shipped “stateful reconnect” negotiate flag and to add explanatory text for the reconnect/ack/replay behavior (especially around Ack and Sequence messages) across transport and hub protocol docs.

Changes:

• Renames the negotiate property from useAck to useStatefulReconnect and replaces the old placeholder link with a new Stateful Reconnect section in the transport spec.
• Extends the WebSockets transport section to describe reconnect/reattach behavior when stateful reconnect is enabled.
• Adds a Hub-protocol Stateful Reconnect section and cross-references from the Ack/Sequence message table entries.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
src/SignalR/docs/specs/TransportProtocols.md	Updates negotiate flag naming and adds transport-level stateful reconnect documentation, including WebSockets reattach behavior.
src/SignalR/docs/specs/HubProtocol.md	Adds hub-protocol semantics documentation for Ack/Sequence and stateful reconnect behavior.

Comments suppressed due to low confidence (2)

src/SignalR/docs/specs/TransportProtocols.md:218

• In this section, the opening description states that “each side buffers … acknowledges … and replays” messages, but the last paragraph says the transport itself does not buffer/ack/replay and that this is defined by the upper layer. Consider rewording the opening paragraph to attribute buffering/ack/replay to the upper layer (e.g., Hub protocol) to avoid implying the transport layer provides these semantics.

Stateful reconnect lets a client transparently recover from a transport-level
disconnect without losing in-flight messages. When enabled, each side buffers
the messages it has sent and the receiver acknowledges the messages it has
processed; on reconnect the unacknowledged messages are replayed in order.

src/SignalR/docs/specs/HubProtocol.md:214

• The duplicate-discard rule in this paragraph is incorrect/incomplete: after a reconnect, duplicates are identified relative to the receiver’s highest already-processed sequence ID (i.e., IDs <= highestProcessed are ignored). In practice, replayed messages can have IDs >= the Sequence.sequenceId but still be duplicates (e.g., replaying IDs that were already processed), so “strictly less than the new starting ID” is not the right condition.

The receiver uses the `sequenceId` from the incoming `Sequence` message to
align its inbound counter and discard duplicates: any subsequently
received trackable message with an ID strictly less than the new starting
ID is a duplicate from before the reconnect and must be ignored.