宿主集成契约（headless / C# 显示宿主同核）

www 工作副本（2026-10-21 Asia/Shanghai）
双轨：正文迁自 mvdocs host-integration（R7）。对照站仍在线。
实现边界：C 导出以 include/vyntek/capi/vyntek_exports.h 为准（NON-STABLE）。PInvoke 在 bindings/csharp/Vyntek.Native，与该头符号对齐；缺符号抛 EntryPointNotFoundException，不静默别名。编排 Run 已实现（src/toolflow/run_session.cpp RunSession::Run：列表序执行、链接拉取、Busy 拒绝、协作取消、abort_on_tool_failure、Outputs 回填；TC-RUN/CTL/LNK 有断言覆盖）。headless 示例：examples/headless_run.cpp（VYNTEK_BUILD_EXAMPLES=ON），含 DEBT-IMG-004 宿主接线示范。
关联：toolflow · csharp-binding · cpp-headers · session-lifecycle · image-display · TC-SESS · TC-DISP

本文钉住宿主形态对照、跨边界规则与停止矩阵的宿主侧分派。执行语义仍只认 toolflow；绑定细则仍认 csharp-binding。

1. 宿主形态对照

宿主	进程语言	如何触达同核	典型职责	不职责
Headless runner	C++（直链）或 CLI	`#include` / 链 `libvyntek_toolflow` · `libvyntek_imaging`，或同形 C 导出	Load `.avtf`、循环 `Run`、收集 Diagnostic	无 GUI；不依赖 ImageDisplay
C# 显示宿主	C#	仅经 csharp-binding PInvoke	Create/Load/Validate/Run；预览交给 ImageDisplay（仅 Controls，M5-10）	不在托管侧重写执行器；不写 C++ UI
产线宿主（可选）	C++/服务进程	同核；MVP 进程内库	批跑；停相机与 Cancel 显式分派	完整 PLC/现场总线不做进 MVP

Headless / C# 显示宿主
        │
        ▼
  libvyntek_toolflow + libvyntek_imaging
        │
        ▼（仅显示宿主）
  PInvoke → ImageDisplay（C#）   观察不驱动 Run

2. 示意 C 导出（非稳定 ABI）

命名前缀 vyntek_toolflow_* / vyntek_imaging_*。句柄 opaque。下表是规格示意；已落地符号见文末对拍，多出来的 try_get / Latest 以头文件为准，不把示意表当成闭集。

能力	符号
Create / Load / Validate	`vyntek_toolflow_create` / `_load` / `_validate`
Run / Cancel	`vyntek_toolflow_session_run` 或 `_run`；`vyntek_toolflow_request_cancel`
诊断	`vyntek_toolflow_diagnostics_count` / `_at` / `_code_at` / `_clear` / `_release`
Adopt / Release	`vyntek_toolflow_adopt_flow` / `_adopt_session` / `_release` / `_session_release`
像素	`vyntek_imaging_handle_adopt` / `_release` / `_share`；`open_read` / `view_close`
取样与预览	`try_get_gray8` / `rgb24` / `bgr24` / `depth16` / `depth_meters`；`acq_session_latest` / `peek_ingress_front`

3. 跨边界规则

规则	口径
Opaque	托管侧不暴露 C++ 布局
Diagnostic 上抛	Load / Validate / Run 的码表不在本文增删
UI 只消费投影	ImageDisplay 不反向驱动执行
观察不驱动 Run	显示与输出观察都不隐式 `Run`
所有权	Adopt 唯一 Release；`view_close` 不释放图像；`Share` 是独立拥有者
同核	headless 与显示宿主链同一对库

4. 停止矩阵：宿主侧分派

权威细则仍是 toolflow §7.4.3（T9）。本仓外形：RunSession::RequestCancel 不调用 AcquisitionSession::RequestStop，反过来也不调用。两端都停须宿主两边都调（session-lifecycle，TC-SESS-05）。关显示不 RequestCancel（TC-DISP-12）。

宿主意图	应调用	不得误调
Cancel Run	`RequestCancel` / `vyntek_toolflow_request_cancel`	不因此停相机；不强制卸 ImageDisplay
停相机	`AcquisitionSession::RequestStop` 再 Drain/WaitStop	不自动 Cancel 在途 Run
关显示	ImageDisplay `Unload` / `Dispose`	不停 Run、不停相机
两端都停	显式停采集并且 `RequestCancel`	禁止一次 SDK.Stop 当成三层全停

5. 回链

目标	用途
examples	`headless_run`
csharp-binding	PInvoke / Dispose
image-display	显示只观察
session-lifecycle	停流

6. 明确不做

不改 Diagnostic 码表，不重写 Run 语义
不写 C++ UI，不承诺稳定 ABI
完整 test-contracts / 场景 S07 全文仍见 mvdocs，本页不把勾选标成通过

实现对拍

规格示意	本仓
双库同核	CMake `vyntek_toolflow` PUBLIC 依赖 `vyntek_imaging`
上表 C 符号	均已声明于 `vyntek_exports.h`，PInvoke 同名
headless	`examples/headless_run.cpp` 走公开头 Create/Run/RequestCancel
`.avtf` Load	解析已实现（`src/toolflow/serialize.cpp` `LoadAvtf`/`SaveAvtf`：JSON 解析、`schema_version` 门禁、未知 `type_id`、IoFailure、未知字段保留；TC-SER-01…07 覆盖）。真实算法仍是 stub（Reed 职责；AGENTS.md 明确 stub 不实现真实算法）
显示关宿主	Controls `Unload`/`Dispose` 不调用 `request_cancel`

文档状态：www 工作副本。示意导出 ≠ 已发布 ABI。

宿主集成契约（headless / C# 显示宿主同核）

1. 宿主形态对照Copy Anchor Link

2. 示意 C 导出（非稳定 ABI）Copy Anchor Link

3. 跨边界规则Copy Anchor Link

4. 停止矩阵：宿主侧分派Copy Anchor Link

5. 回链Copy Anchor Link

6. 明确不做Copy Anchor Link

实现对拍Copy Anchor Link