[Runtime Architecture][Phase 13] 审计调用/连接/流计数所有权并增加状态不变量

[SunSi12138]

总跟踪：#67
分析基线：main @ 201b1621cc706ee221e10ac20947af5fc62b087e
阶段依赖：Phase 02 #70、Phase 07 #75
建议交付：一个聚焦 PR；可拆为多个 commit，但合并时不得保留新旧双路径。

Use case

Logical invocation、physical attempt、Session active request、Server connection/global calls、DynamicModule generation 与 stream dispatch 分别计数，但 scope、increment owner 和 terminal owner 缺少统一矩阵。重复 counter 会在 cancel/response/deadline/disconnect/GoAway 竞态下 underflow 或阻塞 drain。

Proposed behavior

本阶段按下述工程原则和任务清单实施。目标不是增加抽象数量，而是减少非法状态、所有权分支、并发状态组合与测试不确定性。

通用工程原则（本阶段必须遵守）

1. 让非法状态不可表示。 构造完成的对象必须立即合法；握手结果、BuildPlan、拓扑和其他稳定配置使用 immutable snapshot 一次发布，不依赖调用顺序完成二次绑定。
2. 单一所有权、单一终态。 每个 transport、counter、lease、timer、后台任务和构建期资源都必须写明谁创建、谁拥有、哪个终态释放、停止或失败时由谁等待/观察；竞争终态必须由同一个 winner 收敛，禁止重复释放和 underflow。
3. 分离状态域。 Session 的 transport/protocol 状态、ClientConnection 的新调用资格、ServerConnectionState 的认证/调用排空状态分别建模，不用一个布尔值或一个巨型状态机互相冒充。
4. 并发必须有界且可监督。 不引入无界队列、无限重试或无人等待的 fire-and-forget；framework-owned detached task 必须登记、观察异常，并在 owner 停止时可 drain。批量 drain 前先关闭 owner-level 写入门槛。
5. 统一时间语义。 UTC 只服务 wire deadline、日志、Activity 和公开诊断；本地 deadline、elapsed、heartbeat、retry、breaker、drain 和 shutdown budget 使用同一 TimeProvider 的 monotonic timestamp，并能用 fake time 确定测试。
6. 资源构建是事务。 Builder 先编译完全验证且不可变的 plan，再 materialize resource，最后 commit 所有权；失败时保留 primary exception，并按登记逆序恰好清理一次。Caller-owned 资源不得被框架擅自释放。
7. 保护热路径。 继续读取 immutable snapshot，不增加全局锁；supervisor、BuildPlan、ManifestSource 查询不得进入每次 RPC/每帧/每 item 路径；不得引入无依据的每调用 allocation 或新的锁竞争。
8. 明确兼容性边界。 默认保持 Protocol v2 wire format、Contract ID/Method ID/DTO member ID 与 schema 规则；CLR/source API 和 Generated ABI 可以 breaking，但必须显式升级版本、注册/启动阶段 fail fast，且不保留 legacy constructor、Default Context、reflection adapter 或旧 ABI 转接层。
9. 增量实施、独立验证和回滚。 每个阶段对应一个聚焦 PR，可单独测试、基准和回滚；不一次性重写 Runtime，也不为了目录整齐或抽象形式扩大范围。
10. 保留已经正确的并发模式。 例如 StreamManager.CompleteAll 先 CAS 发布终态再逐 stripe drain、PendingCall 单槽位终态竞争、dispatcher acquire/close/detach lease；不得以“统一”为名改成全局锁或 ConcurrentDictionary 全面替换。
11. 测试与诊断先行。 生命周期变更必须有竞态、fault-injection、fake-time、stress/chaos、ALC/NativeAOT（按影响范围）测试；触及热路径时必须提交 BenchmarkDotNet 前后数据。
12. 每个新增可变状态都回答四个问题。 谁创建？谁拥有？哪个终态释放？停止/失败时如何被等待和观察？无法用一两句话回答时不得合并。

本阶段任务

• 建立并落入代码/文档的 ownership matrix：LogicalInvocationCount、PhysicalConnectionCallCount、可能的 SessionActiveRequestCount、ServerConnectionActiveCalls、ServerGlobalActiveCalls、DynamicModuleCall/StreamLease、StreamDispatchLease。
• 对每个 counter 列出 scope、增加点、唯一终态释放方、drain/selection/metrics 用途；全仓追踪调用点和异常路径。
• 审计 RpcSession._activeRequests：若无独立于 ClientConnection/Server connection 的协议语义则删除；若保留则按真实含义改名并添加 invariant。
• 对同步 acquire/finally 使用 allocation-free readonly struct lease；多终态 PendingCall 继续 owner callback；DynamicModule lease 保留。不要为语法统一引入 per-call class allocation。
• 增加状态映射断言（只在 transition/test/debug 边界）：ClientConnection.Ready => Session.Ready && CanAcceptCalls；Server Ready => authenticated && negotiated；Session Stopping => send pump stop requested && stream termination published 等。
• 通过 Phase 07 supervisor/stop 顺序验证 draining：新调用不再进入 ready snapshot，既有 Response/Stream/WindowUpdate/Cancel 能完成。
• 保留 StreamManager CAS terminal barrier + striped drain、dispatcher lease、late frame 有界统计；不引入跨 stripe 总锁。
• 建立 response/cancel/deadline/disconnect/GoAway 与 module replace/unregister 的全排列或系统化 race/chaos 测试。

交付物

• 可执行的 counter/lease ownership matrix。
• 重复 counter 删除或语义化重命名及状态 invariant helpers。
• Call accounting/drain/module/stream race 测试。

验收标准

• 所有 active counter 有唯一 scope、increment owner、terminal owner 与用途。
• 无独立语义的重复 Session/Connection counter 已删除。
• 所有终态竞态后 counter 最终归零，无 underflow、双重释放或 drain hang。
• Draining 关闭新调用但不破坏既有调用控制帧。
• invariant assertion 不进入每帧热路径，lease 不增加可测 per-call allocation。

本阶段补充验证

• Call accounting race/chaos、multi-cluster/dynamic module、graceful drain、StreamManager tests。
• Pending/connection selection/stream dispatch 基准，验证无 allocation 与锁竞争回退。

通用验证门禁

基础门禁（按本阶段影响范围运行，并在 PR 中记录命令与结果）：

dotnet build Sharplink.slnx -c Release
dotnet test --project test/SharpLink.UnitTests/SharpLink.UnitTests.csproj -c Release
dotnet test --project test/SharpLink.Generator.Tests/SharpLink.Generator.Tests.csproj -c Release
dotnet run --project test/SharpLink.IntegrationTests/SharpLink.IntegrationTests.csproj -c Release -- --timeout 120s

触及 Session、Transport、TimeProvider、DynamicModule 或 generated ABI 时，补充相关的 SharpLink.AotSmoke、SharpLink.ChaosTests、TransportConnectionIntegrationTests、RuntimeAssemblyIntegrationTests、RuntimeMultiClusterIntegrationTests、SendPumpTests、RpcSessionLifecycleTests、StreamManagerTests。

若改动进入 Unary 调用、PendingRequestTable、StreamManager、SendPump、P2C 或 codec resolve 热路径，必须提供 BenchmarkDotNet 前后对比：不得无说明增加每调用 allocation；吞吐回退超过基准噪声（CI 稳定前人工参考 3%–5%）时阻塞；p99 不得出现由新抽象引起的锁竞争。

Compatibility and performance impact

不改变 RPC wire 或逻辑/物理指标定义，除非 issue 明确记录重复/错误计数修复。删除 counter 前必须证明无独立语义；不接受“保险起见”保留两套。

风险与回滚

错删 counter 可能破坏 P2C、limit 或 drain。删除前记录依赖并用 stress/chaos 证明；可恢复某一具体 counter，但必须补齐独立语义，不能无说明复制计数。

Out of scope

consumer-abandoned busy polling 的信号实现由 Phase 14；不重写有界表/分片容器。

Alternatives considered

不采用长期保留 legacy constructor、obsolete forwarding overload、Default Context、Runtime reflection adapter、旧 Generated ABI adapter、无界任务/队列或全局锁的方案。若真实扩展需求出现，应设计窄而稳定的新 SPI；若阶段实现需要扩大到无关 package/子系统，应另开 issue 并给出可验证收益。

Checks

• 已搜索现有 Issues 与当前文档，未发现同一实施阶段的重复 issue。
• 本 issue 保留了原实施方案的阶段任务、通用原则、验收、兼容性、性能和回滚约束，并补充了可执行细节。

[SunSi12138]

Implementation Supplement — Phase 13 执行手册（保留原正文）

本阶段是 correctness-first lifecycle accounting refactor。与 #78–#80 不同，它会直接碰 per-call / connection / stream 热路径，所以必须保留最小性能门禁：不能因为“统一计数”引入 per-call class allocation、全局锁或额外 dictionary lookup 热点。但性能不是目标本身，首先要证明每个计数器的语义和唯一终态。

0. 不要先删 counter；先画 ownership matrix

当前代码至少有以下独立 accounting：

• Client logical invocation：SharpLinkClient._activeLogicalInvocations
• Client physical connection call：ClientConnection._activeCallCount
• Session request：RpcSession._activeRequests
• Server per-connection call：ServerConnectionState._activeCalls
• Server global call：SharpLinkServer._globalActiveCalls
• Dynamic module：SharpLinkDynamicModule striped call/stream counters + lease
• Stream lookup/dispatch：StreamManager.DispatcherEntry active dispatch count + close/detach
• StreamManager 业务 stream count：_activeStreamCount

开始实现前创建一张实际文档/测试 fixture 使用的表，每一行必须填写：

Name
Scope / owner object
What exactly is counted
Increment/acquire function
Unique terminal release function
Can increment fail after partial acquire?
Which state transition blocks new acquire?
Which drain/selection/metric reads it?
Underflow behavior
Hot-path frequency

任何一栏答不出来，先搜索所有调用点，不允许删除。

---

1. 先分别定义“logical invocation”和“physical attempt”，不要因为数字接近就合并

Client 当前 _activeLogicalInvocations 在公开调用入口增加，并由 ValueTask/IAsyncEnumerable completion wrapper 在整个逻辑调用结束时释放。重试场景下一个 logical invocation 可以产生多个 physical attempt。

ClientConnection._activeCallCount 则绑定一个具体 physical connection/pending slot，PendingRequestTable 通过 IPendingCallOwner.OnPendingCallRegistered/Completed 管理；另有 TryBeginUntrackedCall/EndUntrackedCall。

因此这两个 counter 有天然不同语义：

• logical count：outer client lifecycle/drain；
• connection count：P2C/connection retiring/capacity/idle drain。

不要为了“统一”删除其中一个，除非全仓证明其读者和终态都可以由另一个严格替代。

---

2. RpcSession._activeRequests 是本阶段必须审计、但不能凭名字直接删的对象

当前 RpcSession 自己还有：

_activeRequests
AddActiveRequest()
ReleaseActiveRequest()
ActiveRequestCount
CanAcceptCalls / IsDraining

执行步骤：

1. 全仓 search AddActiveRequest, ReleaseActiveRequest, ActiveRequestCount；
2. 对每个 caller 标注 client/server/both；
3. 查它是否影响：
   • flow control；
   • GoAway/drain；
   • send pump；
   • metrics；
   • protocol admission；
4. 与 ClientConnection/ServerConnectionState 的 counter 一一比较 acquire/release 边界；
5. 写一个“相同 call 在各 counter 生命周期的时间轴”。

只有确认它没有任何 Session-specific protocol semantic 时才删除。

如果保留，必须改成真实含义，例如 ActiveProtocolRequests，并明确它为什么不能由 connection owner 替代。

不要出现“保险起见两个都留着，但希望永远相等”的状态；那就是重复 source of truth。

---

3. Server accounting 要看 acquire 的两阶段 rollback

当前 SharpLinkServer.TryAcquireCall(connection) 会同时涉及：

• connection.TryAcquireCall(maxPerConnection)
• _globalActiveCalls

ReleaseCall(connection) 则 global decrement + connection decrement，并在 global 归零后完成 _callsDrained。

低级 AI 很容易重构成：

++global
++connection

然后忘记第二步失败时 rollback 第一项。

正确抽象应把“双重 capacity acquire”当作一个事务：

try acquire connection
try acquire global
if global fails -> release connection immediately
success -> return lease/token

最终 terminal owner 只能释放一次。

---

4. 如果引入 synchronous struct lease，必须真的 allocation-free 且单 owner

适用场景是这种同步 acquire / finally Dispose()：

if (!TryAcquire(..., out lease)) reject
try { ... }
finally { lease.Dispose(); }

建议：

internal readonly struct CallAccountingLease : IDisposable

但要特别注意：readonly struct 可被复制。 如果两个 copy 都 Dispose，就会双重 decrement。

因此只有在使用方式能保证 lexical single owner 时使用 struct lease；不要把它：

• 存进 field；
• 放进 collection；
• 跨 async await 保存；
• 传给多个 owner；
• boxing 成 IDisposable。

若生命周期跨 async/多终态，继续用已有 PendingCall owner callback / DynamicModule lease 单终态机制，不为了语法统一强塞一个可复制 struct。

如需跨 async 的 lease，必须有内部 shared terminal state 或继续保留原 owner 模型；不能靠“大家记得只 Dispose 一次”。

---

5. DynamicModule lease 不要被普通 counter abstraction 吃掉

SharpLinkDynamicModule 当前使用 striped _callCounters/_streamCounters，并通过 SharpLinkDynamicModuleLease 与 module draining/unregister 生命周期绑定。

它不仅是统计数字，还参与：

• module replace/unregister drain；
• forced cancellation；
• collectible ALC 生命周期。

因此不要把它换成一个全局 ActiveCounter 类。最多统一 ownership 文档/测试命名，不统一并发实现。

---

6. StreamManager 的 active dispatch lease 与 active stream count 是两个状态域

不要混淆：

• _activeStreamCount：注册的业务 stream 数；
• DispatcherEntry._state count：已经 acquire lookup、可能仍在执行 decode/dispatch 的并发 operation 数；
• Close/Detach：禁止新 acquire + 等旧 acquire drain + pooled dispatcher reuse barrier。

CompleteAll 当前先发布 termination，再逐 request/stripe drain 的模式必须保留。

禁止把这些统一成一个 connection-level lock/counter，因为它会破坏已有 close-vs-dispatch correctness。

---

7. 建立“每种终态谁赢”的表，而不是 scattered finally

至少对 Client pending call 列出：

Response success
Remote error
User cancellation
Deadline
Connection fail
GoAway/drain rejection
Consumer abandoned
Send failure

对每种情况标注：

• 哪个 CAS/table removal 是 terminal winner；
• winner 是否调用 owner completion；
• loser 做什么（no-op / late response metric / bounded log）；
• physical call counter 在哪里释放；
• logical invocation 在哪里释放。

Server 同样列：

normal return
handler throw
cancellation
deadline
disconnect
forced stop
admission reject before acquire
dynamic module drain

任何路径如果有两个独立 finally --counter，都要证明它们对应不同 scope，而不是 double release。

---

8. 状态 invariant 只放 transition/debug/test 边界

推荐 internal helpers：

AssertClientConnectionInvariant()
AssertServerConnectionInvariant()
AssertSessionInvariant()

但不要每个 frame/item 调。

可断言示例：

• ClientConnection Ready => Session.CanAcceptCalls 且 session 未 draining；
• ClientConnection Closed => 不进入 ready snapshot；
• Server connection Ready => handshake/auth/negotiation 已完成；
• Server Draining => no new call admission；
• Session Stopping/terminal => stream termination 已发布、send pump stop 已请求（按实际 Phase 07 状态模型填写）。

invariant helper 不要通过获取多个现有锁形成新的 lock ordering。优先只读 Volatile snapshot，并允许只用于 debug/test。

---

9. deterministic race tests 比“循环 10 万次没挂”更重要

至少人为卡住以下窗口：

1. ClientConnection first CanAcceptCalls check 后立即 MarkDraining，再继续 increment/recheck；
2. Server connection acquire 成功、global acquire 前 server 开始 draining；
3. Response 与 cancellation 同时竞争 PendingCall terminal；
4. deadline 与 disconnect；
5. consumer abandon 与 remote complete；
6. GoAway 与新 attempt selection；
7. dynamic module TryAcquire 与 BeginDraining；
8. module unregister 与 active stream lease release；
9. StreamManager lookup acquire 后 CompleteAll；
10. dispatcher detach 与 last active dispatch release。

每个测试最后断言所有相关 counter 精确归零，不只是“不抛异常”。

再用 stress/chaos 覆盖随机排列，但 stress 不能替代 deterministic barrier test。

---

10. 删除 counter 的安全步骤

如果某 counter 被证明重复：

1. 先新增 invariant/test，证明其值能由 surviving state 推导；
2. 删除 读者 或迁移读者；
3. 再删除 increment/decrement；
4. 最后删除 field；
5. 全仓 search field/API 名；
6. 跑 drain/capacity/P2C/metrics tests。

不要先删 field 再根据编译错误猜 semantics。

---

11. 性能门禁只针对实际热路径变化

本 phase 需要最小 benchmark，因为 accounting 本身发生在 per-call/selection/stream lifecycle。

至少复用/扩展现有 hot-path benchmark 验证：

• Pending register + complete：Allocated B/op 不增加；
• connection call acquire/release：不新增 class allocation；
• P2C/ready connection selection：如果 invariant/accounting 改到 selection，不新增全局锁；
• StreamManager attached dispatch：不因统一 counter 增加锁/atomic 次数；
• DynamicModule acquire/release：若改动它，保持 striped 行为。

这里不要求“必须变快”。要求是 重构不产生可测的新成本：

• 0 B/op baseline 不得变成稳定 per-call allocation；
• 不新增 global lock；
• throughput/Mean 若超出正常噪声（人工参考 3–5%）回退，先 profile 原因。

如果性能回退来自新增通用 abstraction，而 correctness 并不需要它，应撤回 abstraction，保留更直接的 owner-specific实现。

---

12. 推荐 commit 顺序

1. docs/test: add accounting ownership matrix and terminal-race tests
2. refactor: make client logical/physical ownership explicit
3. refactor: audit/remove-or-rename session request accounting
4. refactor: make server dual call accounting single-terminal
5. test: add invariant/debug assertions and chaos coverage
6. cleanup: remove proven duplicate counters/helpers

DynamicModule/StreamManager 只有在 matrix 发现真实问题时改；不要因为 phase 名叫“统一所有权”就重写所有并发结构。

---

13. 回退条件

• 无法说清某 counter 的唯一 terminal owner；
• struct lease 可复制导致 double Dispose 风险；
• async 生命周期被强行塞进 synchronous lease；
• 删除 counter 后 drain/capacity/P2C 需要靠另一个近似值猜；
• invariant 引入 lock ordering；
• per-call allocation 从 0 变非 0；
• 把 StreamManager/DynamicModule 已证明正确的专用并发模型统一成更粗的全局锁。

出现这些情况，撤回对应小 commit，不要继续叠补丁。