Session
三类「会话」表面（勿混名）：
| 表面 | 头 | 状态 |
|---|---|---|
编排 vyntek::toolgroup::RunSession | toolgroup/run_session.hpp | Run/RequestCancel 已实现（列表序执行、Busy、协作取消、abort、Outputs 回填）；GetOutput 做标量投影（图像句柄无字符串形式故空串），≠ 观察面；SetToolWorkDoneHook（DEBT-IMG-004：宿主联到采集端停流门的可选回调，不自动链接 AcquisitionSession）；仍 NON-STABLE |
采集 vyntek::imaging::AcquisitionSession | imaging/acquisition_session.hpp | 停流骨架 + 有界入口 + Latest 预览槽 + ResourceDiagnosticsSnapshot；NON-STABLE |
扁平 vyntek::Session | session.hpp | 空壳占位（仅默认构造/析构；拷贝删除）；勿用于实跑（P1-06） |
规格正文：session-lifecycle · camera-acquisition · TC-SESS · TC-ACQ
AcquisitionSession（按实 · imaging/acquisition_session.hpp）
| 成员 / 类型 | 说明 |
|---|---|
AcquisitionState | Idle / Armed / Running / Quiescing / Draining / Cancelling / Releasing / Returning / Stopped / Faulted |
kIngressCapacity = 8 · kReturnQueueCapacity | 有界入口 / 有界归还工作队列常量 |
state() / name() / ingress_size() | 只读查询 |
Arm / Start | 装填 / 启动 |
RequestStop / RequestCancelStop | 停流相位（优雅 / 中止）；不调用 RunSession::RequestCancel（M3-07：两端各自显式停）；Draining 中请求中止 → InvalidOperation |
Drain / PumpOnce | 停流相位推进；Running 时 PumpOnce 驱动 M4-04 归还泵 |
WaitStop / PumpUntil（别名） | 超时留在 Returning，cleanup_continues；不假装 Stopped |
stop_outcome() / stop_faults() | StopOutcome（Running / StoppedOk / StoppedWithExternalHold / TimedOutCleanupContinues / Faulted）· StopFaults（return_failed_count / camera_disconnected / consumer_fault / return_queue_overflow） |
stop_progress() | StopProgress 五条件联合门：ingress_empty / owned_refs_closed / returns_complete / tool_work_done / !external_retention；ready_to_stop() / claims_device_returned() |
WaitStop(StopTimeout, StopSummary*) | StopTimeout{budget_ms}（0 = 无时钟上限）· StopSummary（timed_out / cleanup_continues / has_external_hold / outstanding_returns / active_access_count / grant_queue_depth / return_queue_depth） |
TryPostOwned | 有界入口（kIngressCapacity=8）；满 / 错误状态 → InvalidOperation；!buffer → InvalidArgument；配合 PostOwnedOrClose 适配器辅助 |
Latest() | 有所有权预览槽（最近一次成功 TryPostOwned 的 Share；替换即关上一预览） |
PeekIngressFront() | FIFO 队首 Share；不是 Latest |
outstanding_returns() / set_outstanding_returns_query | 归还轮询（可注入；无 OnReturnCompleted 回调，设计使然） |
SetOutstandingReturnsForTest / SetReturnFailedCountForTest | 冒烟测试桩 |
SetOwnedRefsClosed / SetToolWorkDone | 联合停流门条件覆盖（冒烟；tool_work_done 默认 true） |
ResourceDiagnostics() | ResourceDiagnosticsSnapshot（接收/拒绝/预览替换/入口高水位与容量、outstanding_returns / return_work_depth / active_access_count / grant_queue_depth / return_queue_depth / return_failed_count、tracked_buffers[]（id / generation / hold_duration 微秒，实体 born_at 起算，实体擦除报 0））；不是 toolgroup::Diagnostic |
Reset() | 复位（清入口/计数/注入查询） |
NoteCameraDisconnected / NoteConsumerFault / NoteReturnQueueOverflow | 外部故障记录；归还队列溢出 → 立即 Faulted |
RunSession 补充（编排端）
SetInput（typed + 字面量重载，类型不符 → TypeMismatch）· Run()（重入 → Busy）· GetOutputValue / GetOutput<T> / GetOutput（string 投影）· ResetOutputs · LastResult（RunResult：status / ok() / failed_tool_id / message）· RequestCancel / cancel_requested · SetRunProbe（冒烟门：观察不得驱动 Run）· SetToolWorkDoneHook（Run 进入/离开执行各回调一次；Busy 早退不回调）。详见 ToolGroup 页。
vyntek::Session（扁平伞头占位）
仅默认构造 / 析构；拷贝已删除。无生命周期、绑定、Cancel、排空 API。