feat: 增加会话感知的发送确认与消息上下文

[CSJ608]

背景

StreamConnection<TMessage>.SendAsync 当前在消息写入连接级发送队列后完成；发送失败时，尚未发送的消息会保留在队列中，并由重连后的新会话继续发送。这个语义适合允许重放的普通业务协议，但部分有严格会话边界的协议需要更强的保证。

以 HSMS-SS 为例：

• TCP 重连后是一个全新的 HSMS 会话，必须重新完成 Select；
• 旧会话中的数据消息不能自动在新会话重放；
• T3/T6 等协议计时器应从整帧实际写完 Socket 后开始，而不是从成功入队时开始；
• 接收侧需要识别消息所属会话，避免旧解码任务的迟到消息被归入新会话。

该需求来自基于 StreamFrame 开发的 CSJ608/SecsFrame，但能力本身不应包含任何 SECS/HSMS 专用概念。

期望能力

希望增加一个向后兼容的高级会话 API；具体命名可以在实现时调整，关键语义如下：

1. 每次成功建立 TCP 会话后产生单调递增、不可复用的 SessionId。
2. 提供绑定当前会话的发送方法，例如 SendInSessionAsync(sessionId, message)。
3. 返回任务只在整帧全部写入 Socket 后完成。
4. 若指定会话在发送完成前终止，任务以明确的会话失效异常或取消结束。
5. 会话失败后的消息不得自动转移到新会话重放。
6. 高级接收 API 能携带消息对应的 SessionId。
7. 保留现有 SendAsync 和跨重连消息流的兼容行为。

建议测试

• 整帧写完之前，发送任务不完成。
• 部分写入后 Socket 失败，发送任务失败且消息不在新会话重放。
• 消息排队期间会话切换，旧 SessionId 的发送失败。
• 重连后新 SessionId 可以正常发送。
• 旧会话解码任务迟到退出时，消息仍带旧 SessionId。
• 并发发送继续保持帧级串行化。

验收标准

• 新能力有清晰的 XML 文档和生命周期说明。
• 不改变现有 API 的行为。
• net8.0、net10.0、net48 测试矩阵全部通过。

[CSJ608]

实现方案（欢迎逐条反馈）

通读现有代码后的设计如下。核心思路：会话概念内部已经存在（_sessionEpoch，用于过期故障防护），把它公开化、并让发送队列和消息通道携带会话归属，即可满足全部语义，不动现有 API。

一、拟定的公共 API

public sealed class StreamConnection<TMessage> : IStreamConnection<TMessage>
{
    /// 当前会话编号：单调递增、跨重连不复用；无会话时为 0。
    /// 仅作发送绑定的"目标声明"，真正的校验在发送 worker 出队时（权威）。
    public int CurrentSessionId { get; }

    /// 绑定会话的发送：整帧全部写入 socket 后才完成。
    /// 会话在完成前终止 → 以 SessionExpiredException 失败；消息不会转移到新会话重放。
    public Task SendInSessionAsync(int sessionId, TMessage message, CancellationToken ct = default);

    /// 高级接收：消息 + 它所属的会话编号（旧会话解码任务迟到的消息带旧编号）。
    public IAsyncEnumerable<SessionMessage<TMessage>> GetSessionMessages(CancellationToken ct = default);
}

public readonly record struct SessionMessage<TMessage>(int SessionId, TMessage Message);

/// 会话已失效：绑定了旧会话的发送无法完成（会话在整帧写出前终止）。
public sealed class SessionExpiredException : Exception
{
    public int SessionId { get; }
}

现有 SendAsync（入队即完成、断线重放）/ GetMessages（跨重连稳定流）行为一字不改。

二、关键语义逐条对照

Issue 要求	方案
1. 单调递增不复用的 SessionId	直接公开内部 epoch。注意：现有防过期机制在 Retry 与 StartSession 各自增一次，编号可能有间隔（1,3,5…）——单调性与不可复用不受影响，如需连续编号要做小重构（动过期防护逻辑，风险更高，倾向不做）
2. 绑定会话的发送	SendInSessionAsync，见上
3. 整帧写完才完成	worker 在 SendRawAsync（现有"循环 SendAsync 到整帧写完"）返回后完成该条目的 TCS。"写完"的精确定义：整帧字节已交给本机 socket（内核缓冲），不含对端 ACK——这是应用层可得的最好信号，T3/T6 从此起算是够用的
4. 会话终止→明确失败	出队时 sessionId != 当前会话 → 立即 fault 该条目（SessionExpiredException），不发送；发送中途 socket 失败 → fault 并上抛触发既有重连
5. 不跨会话重放	会话绑定条目在任何失败路径下都不重入队；普通 SendAsync 条目维持现有重放行为
6. 接收带会话	内部 relay 通道元素从 TMessage 改为信封（解码器按会话构造，产出时盖上自己的会话编号——旧解码任务迟到退出时天然带旧编号）；GetMessages 解包投影，外部行为不变
7. 现有 API 不动	见上，现有测试全部原样保留作回归

三、Torn frame（最想请确认的一条）

整帧写到一半会话死了：任务判失败（整帧未写完），已上线的半截字节不可撤回。理由：此时 TCP 必然也在死亡路径上（对端要么收到 RST、要么靠自己的超时/KeepAlive 收尾），残留半帧不会进入对端正常解码；若追求"可能已送达"的歧义上报（比如再给一个"部分写出字节数"属性），会显著复杂化 API，暂不提供。

→ 请确认：部分写入即整体失败，可接受？

四、排队期间会话切换的失败时机（第二条想确认的）

会话绑定条目入队后、尚未写出时会话死掉：语义上此刻已注定失败。但条目躺在连接级队列里，最早的 fault 时机是下一个 worker 出队时——若重连耗时 30s，调用方就要白等 30s 才拿到本可立即判定的失败。对 HSMS 这类要靠及时失败启动 T5/T6中止计时的协议，这个延迟有实际代价。

方案：维护一个"会话绑定条目注册表"（TCS + sessionId），会话拆除时主动 fault 该会话的全部挂起条目；worker 出队时对过期条目一律跳过不发送（无论 TCS 是否已被 fault）。代价：多一个并发注册表的生命周期管理。

→ 请确认：需要会话拆除时立即失败（推荐），还是接受"下个会话 worker 出队时失败"的简单版？

五、内部实现要点（给 review 的人看路径）

• _sendQueue 元素 TMessage → 内部信封 { Message, SessionId, TaskCompletionSource? }；SendAsync 走无 TCS、SessionId=0 的条目（现有重放语义不变）
• SendWorkerAsync：出队时 HasCompletion && SessionId != 当前 epoch → fault 跳过；写完 → 完成 TCS
• StopSessionCore：拆除会话时 fault 注册表中该会话的挂起 TCS
• Shutdown（Dispose）：TryComplete 后补一轮排空，fault 所有带 TCS 的残留条目——否则挂起的 SendInSessionAsync 永不结束（普通条目按现状静默丢弃）
• 解码器构造时带入会话编号，写入 relay 的每条消息带编号；relay 信封化后 GetMessages 投影解包
• 净效应：队列/通道类型各改一处，worker/停机路径改动集中，SendAsync/GetMessages 语义由现有测试锁死

六、测试清单（在 issue 建议基础上补三条）

issue 已列 6 条全收，另补：

• Dispose 时存在挂起的会话绑定发送 → 全部以异常收尾、不悬挂；
• SessionId 跨多次重连单调且不复用；普通 SendAsync 消息在会话切换后仍被重放（锁定与绑定发送的行为差异）；
• GetMessages 与 GetSessionMessages 看到同一消息序列（信封不丢不重）。

七、实施切分

一个 PR、按主题分 commit（发送侧 / 接收侧 / 文档）；如 reviewer 更希望小步合入，可拆两个 PR：①SessionId + 发送侧，②接收侧信封 API。CHANGELOG 记 Unreleased 新增；README 增"会话感知收发（高级）"一节，重点写清生命周期与"写入 socket ≠ 对端已收"的边界。

[CSJ608]

感谢详细方案。两个需要确认的问题，结论如下。

1. Torn frame

接受“部分写出后，本次发送整体失败”的语义，也同意首版不增加“已写出字节数”之类的公共属性。

不过建议把文档中的因果表述收紧：发送任务失败时，远端是否已经收到完整帧可能存在不确定性，不能保证一定只留下不会被解码的半帧。公共保证应是：

• 本地没有得到“整帧已交给本机 socket”的完成确认；
• 本次会话绑定发送以失败结束；
• 该消息绝不自动转移到新会话重放；
• 调用方应把远端处理结果视为未知，并由上层协议的事务关联、幂等或恢复流程处理。

这比承诺远端一定未收到更符合 TCP 发送失败和取消竞态的实际边界。

2. 会话拆除时的失败时机

需要会话拆除时立即 fault 该会话的全部挂起发送，不接受等到下一会话 worker 出队时再失败的简单版。

对 HSMS 来说，排队条目已经绑定旧 TCP 会话；旧会话结束后继续等待重连没有业务意义，还会延迟 T3/T6 等上层计时器和状态机的收尾。建议保留注册表方案，worker 对已完成或过期条目继续做幂等跳过。

3. 建议补入实现与验收条件

1. 不要直接把 _sessionEpoch 暴露成 CurrentSessionId。 当前 epoch 在 Retry 和 StartSession 都会递增，且无会话期间仍为非零，与“无会话时为 0”的公共契约冲突。建议维护独立的公共连接会话编号；编号可以有间隔，但只在真实 TCP 会话建立时分配，拆除时当前值归零。建议使用 long 并对耗尽显式失败。

2. 明确会话建立/状态发布的线性化点。 当前 CommunicationStateChanging(Connected) 会先发布 ConnectionChanged、完成 WaitForConnectedAsync，之后才调用 StartSession。若新增 CurrentSessionId，调用方可能在 Connected 回调或等待完成后仍读到 0/旧值。应保证“Connected 可见”时有效会话编号已经可见，或者增加独立、携带编号的会话事件/等待 API。拆除方向同理：Retry/Disconnected 对外可见时，旧会话应已不可用于新发送。

3. 关闭注册与拆除之间的竞态。 “校验当前会话 → 注册 TCS → 写入有界队列”期间可能恰好拆除会话。注册和拆除需要共享线性化机制，或采用“先注册、再复核当前会话”的双检方案。还应覆盖队列已满、WriteAsync 正在等待时会话失效：调用任务必须及时结束，迟到进入队列的旧信封只能跳过，不能发送。

4. 定义调用方取消的提交点。 在 worker 尚未开始发送前，取消可以使条目退出并由 worker 跳过；一旦开始向 socket 写帧，不建议把调用方 token 直接传给共享 socket 写入，因为取消一条消息不应任意撕裂帧或杀死整条连接。开始发送后应由会话 token 控制写入，或明确选择“取消即终止会话”的更强语义。对 SecsFrame，前一种语义更合适。

5. 避免破坏现有接口实现者。 如果把新成员加入 IStreamConnection<TMessage>，第三方实现会发生源码兼容性破坏。建议新增可选能力接口，例如 ISessionAwareStreamConnection<TMessage> : IStreamConnection<TMessage>，由 StreamConnection<TMessage> 实现；仅放在具体类上虽然兼容，但依赖接口的上层无法使用。

6. 说明两个接收 API 不是广播。 如果 GetMessages 和 GetSessionMessages 投影同一个 relay channel，同时枚举会竞争消费，不会各自看到完整副本。建议把它们定义为二选一的消费视图并明确单消费者约束；不需要为此引入广播及其背压复杂度。“看到同一消息序列”的测试应在独立连接/独立运行中比较。

4. 建议增加的竞态测试

除现有清单外，建议覆盖：

• Connected 回调及 WaitForConnectedAsync 完成后立即读取会话编号，必须有效且一致；
• 会话拆除与注册挂起发送并发，循环运行不出现漏 fault 或跨会话发送；
• 有界发送队列已满时拆除会话，等待入队的绑定发送及时失败；
• 调用方取消与 worker 开始发送竞争，只有一个明确结果，且不留下悬挂 TCS；
• 整帧写完与会话拆除竞争，完成/失效按同一线性化规则二选一；
• GetMessages / GetSessionMessages 的消费互斥或竞争语义有明确测试。

整体方向认可。满足以上边界后，这套 API 可以替换 SecsFrame 当前针对 #39 的内部会话编号、编码前校验和 RawBytesSent 发送完成适配。

[CSJ608]

回执：全部采纳，按以下方式落地

1. Torn frame 文档口径：按你的四条公共保证写——本地未取得"整帧已交给本机 socket"的完成确认；本次发送以失败结束；绝不转移到新会话重放；远端处理结果视为未知，由上层协议的事务关联/幂等/恢复流程兜底。不承诺"远端一定未收到"。
2. 失败时机：会话拆除时立即 fault（注册表方案），worker 对已完成/过期条目幂等跳过。
3. 独立公共会话编号：不暴露 _sessionEpoch。新增 long 编号，仅在真实 TCP 会话建立时分配（有间隔、单调、不复用），拆除发布前归零（无会话 = 0）；checked 递增，耗尽显式抛出。
4. 线性化点：Connected 发布（事件回调、WaitForConnectedAsync 完成）之前完成编号分配——回调里读 CurrentSessionId 必为有效值；Retry/Disconnected 发布之前归零——状态对外可见时旧会话已不可用于新发送。
5. 注册/拆除竞态：注册 → 复核当前编号的双检 + 状态字 CAS（排队中→已认领/已取消/已失效三向互斥）；队列满、WriteAsync 等待期间会话失效 → 调用任务及时结束，迟到入队的旧信封只跳过不发送。
6. 调用方取消的提交点：worker 认领（CAS）前，取消使条目退出、worker 跳过；认领后写入只受会话令牌控制，迟到取消对任务结果无副作用（即"提交点 = 认领"）。不把调用方 token 传给共享 socket 写入。
7. 能力接口：新成员放 ISessionAwareStreamConnection<TMessage> : IStreamConnection<TMessage>，不动 IStreamConnection，第三方实现者不受影响。
8. 接收 API 非广播：GetMessages / GetSessionMessages 定义为二选一的消费视图（同一通道的竞争消费者，单消费者约束写入两处 XML 文档）；"同一序列"测试按你的建议在独立连接/独立运行中比较。
9. 竞态测试：你列的 6 条全部纳入测试清单（Connected 后立即读编号的一致性、拆除与注册并发压测、队满拆除及时失败、取消与认领竞争单结果、整帧写完与拆除竞争二选一、双接收视图竞争语义）。

开始实现，PR 会关联本 issue。