流程会话停止、故障与最终回收

www 工作副本 · M3（Arden · 2026-10-21 Asia/Shanghai）
双轨：本页已迁入 Vyntek www；mvdocs session-lifecycle 仍在线对照。
实现边界：对拍 tip e46c042。imaging/acquisition_session.hpp 停流态与 RequestStop / RequestCancelStop / Drain / WaitStop 外形在。联合结束以轮询 outstanding_returns() 为骨架（无 OnReturnCompleted）；StopProgress::external_retention 与 claims_device_returned() 在；超时保持 Returning 且 cleanup_continues（不假装 Stopped）；return_failed_count>0 完成 Returning → Faulted。RequestStop 不自动调用 RunSession::RequestCancel。有界入口 kIngressCapacity=8。全部仍 NON-STABLE / STUB，TC-SESS 未验收。Arden 不改实现。可勾选薄摘见 test-contracts-tc-sess.md。
关联：overview · memory-management · image-model · cpp-headers · camera-acquisition · 预览 http://127.0.0.1:8792

目标设计与 API 草案，尚未完整实施。总体边界和推进状态见设计概述。

编排权威见 toolflow.md。本文只负责停流/故障时的结束屏障与真实归还协调。边界：ToolFlow Run/RunSession（编排）≠ 采集入口队列（成像）≠ ImageDisplay 消费者（显示）；本文协调其共同退出，不另立图调度模型。

本文负责采集入口、在途工具工作、观察、显示与 SDK 的结束屏障；取消不等于实际结束，工具/Run 返回不等于真实归还。

关联：内存 · 采集 · ToolFlow（编排） · 宿主集成（R7 停止矩阵宿主侧分派） · 诊断 · 测试契约薄摘 TC-SESS-*（Arden · R10；全文仍在 mvdocs test-contracts） · 场景 S11

停止协议由会话/采集集成层执行，图像基建提供独立引用、访问协调和 ReturnCompleted；ImageDisplay 不负责停止相机或整个工具流（显示只观察）；编排 Cancel 语义以 toolflow §7.4.3 为准（停相机 ≠ 自动 Cancel Run）。详见下文停止矩阵。

Running
  → Quiescing：停止接受新工作，退出采集回调，保持归还泵可用
  → Draining / Cancelling：按策略消费或丢弃待处理项，等待正在运行的实际工作
  → Releasing：关闭输入/输出/缓存/预览/显示的自有引用
  → Returning：等待 SDK 归还回调与清理队列
  → Stopped：没有该会话拥有的在途工作或外借资源

可靠结束可选择排空队列；立即中止则取消工具并关闭未消费项。取消不是强制终止线程：正在运行的工具、native 调用和 pin 只有在实际访问结束后才能退出。SDK 若要求先归还全部帧才能 Stop/Close，应把其停止采集命令拆成“停止产生新帧”和“销毁池/设备”，按其协议安排，不能把上述逻辑顺序机械翻译为单次 SDK.Stop 调用。

停止矩阵（与编排三层对齐 · T9）

Alive 拍板。权威细则与可测码见 toolflow.md §7.4.3；采集见 camera-acquisition.md；显示见 image-display.md。本文负责会话排空/归还，不把三层收成一次 SDK.Stop。

动作	编排（`RunSession`）	采集	显示
Cancel Run	协作式；当前 Tool 返回后不再启动后续；码 `Cancelled`	不自动停相机	只观察；不停编排
宿主停相机	不自动 Cancel 已在跑的 Run	停新帧 + 按协议归还	可能停在最后一帧
显示关闭 / 卸图	不停 Run	不停相机	释放显示自有引用
会话停流（本文状态机）	可显式 Cancel 在途 Run，再 Quiescing→…→Stopped	停接受新工作、排空归还	解除会话拥有的预览引用

宿主若要「相机与 Run 一起停」，必须显式既停采集又 RequestCancel；二者不隐含联动。

结束条件与外部保留

会话记录导入成功的外借资源及归还终态，停止成功要同时满足：没有新回调、队列为空、工具工作已结束、会话拥有的图像及访问已关闭、SDK 归还已完成。关闭最后一个 buffer/image 后再等待归还，不能边持有最后引用边等自己的 ReturnCompleted。

显示和记录也是消费者。会话拥有它们时需排空并解除其图像引用；若宿主明确把图像导出给会话外的窗口/历史缓存，会话停止不再控制该引用。要立即销毁 SDK，应先把这些长期内容复制到独立存储并关闭原图；否则停止只能报告“仍有外部保留”，不能假称设备资源已归还。

超时与故障处置

停止等待可以有调用方超时，但底层安全清理继续运行。超时返回未排空/故障结果，并报告 BufferId、活动访问、pin、等待者、归还队列及持有时长；不能强行回收仍被 native 使用的地址。若工具违反契约遗失访问对象，任务返回也不能证明资源安全，故障需要显式处理而不是自动重用缓冲。

ReturnFailed、相机断线、工具异常、队列消费者退出和解码失败都要进入可观察故障路径。归还失败不自动再次 Release，也不把全部后续资源卡在同一未观察的异常后面；清理泵继续处理其他可归还项，最终停止结果汇总失败。仅当归还条件满足且设备协议允许时销毁 SDK 线程、池和设备上下文。

阶段 D 散文 → 可勾选：TC-SESS-01…05（停流状态机结束条件、外保留 ≠ 假称已归还、超时未排空但底层续清、ReturnFailed/断线可观察、两端都停须显式 Cancel + 停采集）。薄摘表见 test-contracts-tc-sess.md；全文表见 mvdocs test-contracts §9（本波不迁完整 test-contracts）。薄场景 S11。采集入口见 camera-acquisition.md · TC-ACQ 薄摘。停止矩阵语义仍以 toolflow §7.4.3（T9） 为准——不改。

实现对拍：`AcquisitionSession`（tip `e46c042` · 按实）

头：include/vyntek/imaging/acquisition_session.hpp · 实现：src/imaging/acquisition_session.cpp · smoke：tests/smoke_headers.cpp（优雅停流 + Cancel 路径相位推进）。注释仍写 NON-STABLE ABI / STUB / M1-ISSUE-02；头注已指 M3 / session-lifecycle（M3-08）。≠ vyntek::toolflow::RunSession（编排）；≠ 扁平 vyntek::Session 空壳。

已有外形（状态机 · Chase 非拦须反映）

表面	按实（tip `e46c042`）
`AcquisitionState`	`Idle` / `Armed` / `Running` / `Quiescing` / `Draining` / `Cancelling` / `Releasing` / `Returning` / `Stopped` / `Faulted`
`Arm(name)`	Idle\|Stopped → Armed
`Start()`	Armed → Running
`RequestStop()`	Running → Quiescing；已在停流（Quiescing…Returning）时幂等 `Ok`（不跳相）
`RequestCancelStop()`	Running\|Quiescing → Cancelling；Cancelling…Returning 幂等 `Ok`
`Drain()` / `PumpOnce()`（停流中）	各推进一相：优雅 Quiescing→Draining→Releasing→Returning→Stopped；中止 Cancelling→Releasing→Returning→Stopped（`AdvanceStopFlow`）
`PumpOnce()`（Running）	可推进归还泵（M4-04）；不是停流相位
`WaitStop` / `StopTimeout`	超时留在 Returning，`cleanup_continues`；不假装 Stopped
`Reset()`	仅 Stopped\|Faulted → Idle；停流中途不可 Reset
`TryPostOwned` / `Latest`	有界入口（8）+ Latest 预览槽；FIFO = `PeekIngressFront`；Quiescing+ 拒帖
`RequestStop` vs `RequestCancel`	不自动联动；两端都停须调用方两边都调

停流 ASCII（与规格正文一致；已落枚举）：

Running
  → Quiescing（RequestStop）          → Draining → Releasing → Returning → Stopped
  → Cancelling（RequestCancelStop）                 ↗

相对规格仍为 stub / 缺口

规格期望	tip `e46c042` 现状
联合结束条件	骨架：轮询 outstanding、工具工作门、自有引用关闭；无 `OnReturnCompleted`；未验收
外保留	`external_retention` + `claims_device_returned()`；宿主 Share 持有时不能假称已归还
超时续清	`StopTimeout` / `WaitStop`；超时不假装 Stopped
`ReturnFailed` 汇总	`StopFaults::return_failed_count`；完成时 >0 → `Faulted`
两端都停	外形隔离正确；宿主矩阵未测实（host-integration 仍 mvdocs）
TC-SESS-01…05	勾选仍空

禁止把骨架标成 TC-SESS 验收完成。

文档状态：www 工作副本 · M3（2026-10-21，Asia/Shanghai）。T9 停止矩阵与 toolflow v1.9 §7.4.3 双向对齐；宿主侧分派见 host-integration（R7，仍 mvdocs）；可勾选见 Arden · R10（TC-SESS- / S11）。对拍 tip e46c042。*

流程会话停止、故障与最终回收

停止矩阵（与编排三层对齐 · T9）

结束条件与外部保留

超时与故障处置

可勾选契约（Arden · R10 · 薄回链）

实现对拍：`AcquisitionSession`（tip `e46c042` · 按实）

已有外形（状态机 · Chase 非拦须反映）

相对规格仍为 stub / 缺口

On this page

流程会话停止、故障与最终回收

停止矩阵（与编排三层对齐 · T9）Copy Anchor Link

结束条件与外部保留Copy Anchor Link

超时与故障处置Copy Anchor Link

可勾选契约（Arden · R10 · 薄回链）Copy Anchor Link

实现对拍：AcquisitionSession（tip e46c042 · 按实）Copy Anchor Link

已有外形（状态机 · Chase 非拦须反映）Copy Anchor Link

相对规格仍为 stub / 缺口Copy Anchor Link

On this page

停止矩阵（与编排三层对齐 · T9）

结束条件与外部保留

超时与故障处置

可勾选契约（Arden · R10 · 薄回链）

实现对拍：`AcquisitionSession`（tip `e46c042` · 按实）

已有外形（状态机 · Chase 非拦须反映）

相对规格仍为 stub / 缺口