// 与本仓 tests/contracts_run.cpp（TC-RUN-01）同一形状；此处只列公开头
#include <vyntek/toolgroup/toolgroup.hpp>
#include <vyntek/toolgroup/registry.hpp>
#include <vyntek/toolgroup/fake_tools.hpp>
#include <vyntek/toolgroup/run_session.hpp>

using namespace vyntek::toolgroup;

ToolRegistry registry;
fake::register_fake_tools(registry);  // 测试替身；生产配方勿链（TC-REG-06）

auto group = ToolGroup::Create("S01_Single");
Tool* c = group->AddTool(registry.Create("fake_constant", "Const"));  // AddTool 接管所有权，返回非拥有观察指针
// fake_constant 必填配置属性 Value（Int32）；端口 Output（Int32） / FlagOut（Bool）
c->SetProperty("Value", Value::Int32(42));
group->AddOutput("Out", TypeDesc{Type::Int32, {}});
group->LinkToOutput(c, "Output", "Out");   // 工具端口 → 流 Outputs 终端

DiagnosticList diags;
if (!group->Validate(diags)) { /* 期望无 Severity::Error */ return; }

RunSession session(group);  // 构造吃 std::shared_ptr<ToolGroup>
RunResult r = session.Run();
// 断言见下
int  out = 0;
bool got = session.GetOutput("Out", out);  // GetOutput(name, T&) → bool（终端缺失/未设置/类型不符 → false）

auto group = ToolGroup::Create("S02_Chain");
auto* acq = group->AddTool(registry.Create("fake_acq", "Acq"));
auto* pass = group->AddTool(registry.Create("fake_passthrough", "Pass"));
auto* flag = group->AddTool(registry.Create("fake_constant", "Flag"));

group->AddOutput("Image", TypeDesc{Type::ImageGray8});
group->AddOutput("Flag", TypeDesc{Type::Int32});

group->Link(acq, "OutputImage", pass, "InputImage");
group->LinkToOutput(pass, "OutputImage", "Image");
group->LinkToOutput(flag, "Output", "Flag");
// 坏链对照（勿留在成功配方）：group->Link(pass, "OutputImage", acq, "InputImage");
// → Validate 期望 DiagnosticCode::OrderViolation

std::vector<Diagnostic> diags;
assert(group->Validate(diags));
RunSession session(group); // 构造吃 std::shared_ptr<ToolGroup>
RunResult r = session.Run();

auto group = ToolGroup::Create("S03_InspectFake");
auto* acq   = group->AddTool(registry.Create("fake_acq", "Acq"));          // 端口 OutputImage (ImageGray8)
auto* align = group->AddTool(registry.Create("fake_pm_align", "Align"));  // InputImage / OutputImage / Pose (Pose2d)
auto* pass  = group->AddTool(registry.Create("fake_passthrough", "OutImg"));
auto* cnt   = group->AddTool(registry.Create("fake_constant", "Count"));  // 必填 Value
cnt->SetProperty("Value", Value::Int32(0));

group->AddOutput("PoseX", TypeDesc{Type::Float64, {}}); // 示意：从 Pose 最小字段拆出
group->AddOutput("DefectCount", TypeDesc{Type::Int32, {}});
group->AddOutput("Preview", TypeDesc{Type::ImageGray8, {}});

group->Link(acq, "OutputImage", align, "InputImage");
group->Link(align, "OutputImage", pass, "InputImage"); // passthrough 只 ShareImage，不拷像素
group->LinkToOutput(pass, "OutputImage", "Preview");
group->LinkToOutput(cnt, "Output", "DefectCount");
// Pose → 终端：按 §5.1 端点路径（示意）

DiagnosticList diags;
assert(group->Validate(diags));
RunSession session(group);  // 构造吃 std::shared_ptr<ToolGroup>
RunResult r = session.Run();

// 输出观察：只读 LastRun / Outputs；观察回调不得反过来触发 session.Run（TC-OUT-09）
const Value pv = session.GetOutputValue("Preview");
const vyntek::imaging::PixelImageHandle* preview = pv.image();  // Value 直接持句柄；空/类型不符 → nullptr
// 可选：ImageOutputInspector 订阅 EmptySnapshot / Unavailable（T10）— 见 output-inspection / S10

#include <vyntek/toolgroup/serialize.hpp>

// 与本仓 tests/contracts_serialize.cpp（TC-SER-02/03/04）同一形状。
// ToolGroup::Load 与 LoadAvtg 都返回 LoadResult{ shared_ptr<ToolGroup> group; DiagnosticList diagnostics; }

// --- A) 未知 type_id ---
LoadResult bad = LoadAvtg("fixtures/unknown_type.avtg", registry);
// fixtures 内 tools[].type_id = "type_id_not_registered"
assert(bad.group == nullptr);   // 严格失败，无占位成功
assert(HasCode(bad.diagnostics, DiagnosticCode::UnknownTypeId)); // Severity::Error

// --- B) 已知 type、缺必填属性 ---
LoadResult loaded = LoadAvtg("fixtures/missing_required.avtg", registry);
assert(loaded.group != nullptr);  // Load 成功（type 已知；component_version 不拦，T8）
DiagnosticList diags;
bool ok = loaded.group->Validate(diags);
assert(!ok);
assert(std::any_of(diags.begin(), diags.end(), [](const Diagnostic& d) {
  return d.code == DiagnosticCode::MissingRequiredProperty
      && d.severity == Severity::Error;
}));
// 不得出现「静默填默认后 Validate 成功」

#include <vyntek/imaging/handle.hpp>
#include <vyntek/imaging/factory.hpp>
#include <vyntek/toolgroup/toolgroup.hpp>
#include <vyntek/toolgroup/run_session.hpp>

// 流：Acq → CloneThenWrite → Passthrough → Output 终端
auto group = ToolGroup::Create("S05_Handle");
auto* acq = group->AddTool(registry.Create("fake_acq", "Acq"));
auto* wr = group->AddTool(registry.Create("fake_clone_write", "Write"));
auto* pass = group->AddTool(registry.Create("fake_passthrough", "Share"));
group->AddOutput("DisplayImage", TypeDesc{Type::ImageGray8});
group->Link(acq, "OutputImage", wr, "InputImage");
group->Link(wr, "OutputImage", pass, "InputImage");
group->LinkToOutput(pass, "OutputImage", "DisplayImage");

RunSession session(group); // 构造吃 std::shared_ptr<ToolGroup>
RunResult r = session.Run();
const vyntek::imaging::PixelImageHandle* handle = session.GetOutputValue("DisplayImage").image();
assert(handle != nullptr);
assert(handle->access() == vyntek::imaging::BufferAccess::ReadOnly); // H6：链给下游的是只读句柄
// headless：到此为止；句柄经绑定交给 UI 进程/线程（示意）

// 示意、非可编译；仅 ImageDisplay；像素来自 C++ 句柄经 PInvoke 绑定
// 对齐 csharp-binding 与本站 image-display 规格页；控件 API 见 bindings/csharp/Vyntek.Controls/ImageDisplay.cs
using var bound = ImagingBindings.AdoptReadOnly(nativeHandle); // opaque + Dispose
var update = imageDisplay.SetImage(bound); // SetImage(IPixelImage?, InputRetention?) → ImageDisplayUpdate
// 取样 / Depth 选项等见本站 image-display 页；不得在此启动 ToolGroup.Run / Cancel 相机

// --- Cancel：RunStatus::Cancelled（对应 tests/contracts_control.cpp TC-CTL-01）---
auto group_c = ToolGroup::Create("S06_Cancel");
auto* chk = group_c->AddTool(registry.Create("fake_cancel_check", "chk"));
auto* cst = group_c->AddTool(registry.Create("fake_constant", "cst"));
cst->SetProperty("Value", Value::Int32(1));
group_c->AddOutput("Out", TypeDesc{Type::Int32, {}});
group_c->LinkToOutput(cst, "Output", "Out");
RunSession s1(group_c);
// 取消在 Run 在途到达：单测用 fake_cancel_check::set_cancel_hook 在 Run 内触发；
// 真宿主则在另一线程调 s1.RequestCancel()（协作式，T9）
auto* cancel_check = dynamic_cast<fake::FakeCancelCheck*>(chk);
cancel_check->set_cancel_hook([&s1] { s1.RequestCancel(); });
RunResult rc = s1.Run();
// 期望：rc.status == RunStatus::Cancelled；diagnostics 含 DiagnosticCode::Cancelled；
//      cancel_check->saw_cancel()；后续 cst 未 Run（GetOutputValue("Out").empty()）

// --- abort_on_tool_failure：RunStatus::Failed + DiagnosticCode::Aborted（TC-CTL-02）---
auto group_a = ToolGroup::Create("S06_Abort");
auto* bad = group_a->AddTool(registry.Create("fake_fail_always", "bad"));
auto* cst2 = group_a->AddTool(registry.Create("fake_constant", "cst"));
cst2->SetProperty("Value", Value::Int32(3));
group_a->AddOutput("Out", TypeDesc{Type::Int32, {}});
group_a->LinkToOutput(cst2, "Output", "Out");
// abort_on_tool_failure() 默认 true（§4.3；TC-CTL-02 断言此默认）
RunSession s_a(group_a);
RunResult ra = s_a.Run();
// 期望：ra.status == RunStatus::Failed（不是独立的 Aborted 状态）；diagnostics 含 Aborted；
//      ra.failed_tool_id == "bad"；cst 未 Run（H10：不假成功交给下游）

// --- Busy：RunStatus::Busy（TC-CTL-03：同 session 重入拒绝，不排队）---
auto group_b = ToolGroup::Create("S06_Busy");
auto* probe = group_b->AddTool(std::make_unique<ReentrantProbeTool>("probe"));
// 单测用自定义探针在工具 Run 内部再调 session.Run()；真宿主则是第二线程同时 Run
RunSession s2(group_b);
// 线程1：auto r1 = s2.Run(); → r1.ok()，外层 Run 不受损
// 线程2：RunResult rb = s2.Run(); → rb.status == RunStatus::Busy

LoadResult loaded = ToolGroup::Load("recipes/inspect_fake.avtg", registry);
assert(loaded.group != nullptr); // 未知 type / SchemaTooNew 等见 S04
RunSession session(loaded.group);  // 构造吃 shared_ptr；session 不独占 group 所有权（§7.4.5）
for (int i = 0; i < N; ++i) {
  // 可选：注入帧 / 依赖 fake_acq 自产
  RunResult r = session.Run();
  assert(r.ok());
  int n = 0;
  session.GetOutput("DefectCount", n);  // 终端缺失/未设置/类型不符 → false
  // 记录 n；无 SetImage / 无窗口
}

// 示意薄 PInvoke 入口（对齐 csharp-binding）；编排仍在 C++，非第二套 ToolGroup
ToolGroupNative.RunOnce(sessionHandle); // opaque session handle；不在托管侧重写执行器
using var img = ToolGroupNative.GetOutputImage(sessionHandle, "Preview");
imageDisplay.SetImage(img);
// Cancel / 停相机按停止矩阵分派到编排/采集 API，不进 ImageDisplay

#include <vyntek/toolgroup/registry.hpp>
#include <vyntek/toolgroup/tool.hpp>
#include <vyntek/imaging/handle.hpp>

// 最小自定义 Tool（对齐公开头 Tool：type_id / id / name 由基类构造固定）
class ScaleGrayTool final : public Tool {
 public:
  explicit ScaleGrayTool(ToolId id) : Tool(std::move(id), "demo_scale_gray", "ScaleGray") {
    AddInput("InputImage",  TypeDesc{Type::ImageGray8, {}});   // 端口同时是运行时值槽
    AddOutput("OutputImage", TypeDesc{Type::ImageGray8, {}});
    DeclareProperty("Scale", TypeDesc{Type::Float32, {}}, PropertyFlags{true, true, true, true});
  }

  DiagnosticList Run(RunContext& ctx) override {
    DiagnosticList diags;
    const Value in = ReadPort("InputImage");        // 链接拉值由执行器写入端口（§4.2）
    const vyntek::imaging::PixelImageHandle* src = in.image();
    if (src != nullptr) {
      // Clone → OpenWrite → 缩放填充 → Complete → ShareImage → WriteOutput("OutputImage", …)
    }
    if (ctx.cancel_requested) {
      // 协作退出（T9 / TC-CTL-01）；失败/取消不得交出未 Complete 句柄（H10）
    }
    last_run_ = LastRunStatus::Succeeded;   // 失败时置 Failed 并返回 ToolFailure 诊断
    return diags;
  }
  // 其余按 §7.6.1：id/name/enabled/props/Get/Set 由基类提供
};

void register_demo_tools(ToolRegistry& r) {
  r.Register("demo_scale_gray", [](ToolId id) {
    return std::make_unique<ScaleGrayTool>(std::move(id));
  });
  // 重复 Register 同 type_id → 返回 false，不覆盖已有工厂（TC-REG-02）
}

// 测试入口
ToolRegistry registry;
fake::register_fake_tools(registry);   // §7.6.3 清单
register_demo_tools(registry);
auto t = registry.Create("demo_scale_gray", "S");
assert(t != nullptr);
auto missing = registry.Create("no_such_type", "X");
assert(missing == nullptr);   // 调用方映射为 DiagnosticCode::UnknownTypeId（TC-REG-03）

// 示意、非可编译；对齐 toolgroup §9.3 / §9.4 嵌套示意 / §7.4.6 Encapsulation
auto inner = ToolGroup::Create("InnerLocate");
auto* acq = inner->AddTool(registry.Create("fake_acq", "Acq"));
auto* pass = inner->AddTool(registry.Create("fake_passthrough", "Share"));
inner->AddOutput("FixturedImage", TypeDesc{Type::ImageGray8, {}});
inner->Link(acq, "OutputImage", pass, "InputImage");
inner->LinkToOutput(pass, "OutputImage", "FixturedImage");
DiagnosticList inner_diags;
assert(inner->Validate(inner_diags));

auto outer = ToolGroup::Create("OuterMeasure");
// 嵌套不是把 ToolGroup 直接塞进 AddTool；要包一层 NestedGroupTool（toolgroup §3.3 / nested_group_tool.hpp）
auto nested = std::make_unique<NestedGroupTool>("locate", inner, "InnerLocate");
nested->SyncTerminalsFromInner();  // 把内层 Inputs/Outputs 镜像成本工具端口
Tool* locate = outer->AddTool(std::move(nested));  // 内层流仍由 shared_ptr 共享，非独占
auto* flag = outer->AddTool(registry.Create("fake_constant", "WidthFlag"));
outer->AddOutput("Preview", TypeDesc{Type::ImageGray8, {}});
outer->AddOutput("Flag", TypeDesc{Type::Int32, {}});
// 合法：外层只链内层终端（镜像端口）
outer->LinkToOutput(locate, "FixturedImage", "Preview");
// 端点写法等价：outer->Link(LinkEndpoint{locate,"FixturedImage"}, LinkEndpoint{"group","Preview"});
flag->SetProperty("Value", Value::Int32(1));
outer->LinkToOutput(flag, "Output", "Flag");

DiagnosticList diags;
assert(outer->Validate(diags));
RunSession s(outer);
RunResult r = s.Run();
// 期望：r.ok()；Preview / Flag 可读；内层私有 Acq 属性对外不可见

// --- Encapsulation 负例（勿留在成功配方）---
// outer->Link(…, /* 指向 */ "InnerLocate.Acq.OutputImage", …);
// 或 Validate 时发现外层 link 写内层私有路径
// → DiagnosticCode::Encapsulation（Severity::Error）；不留下半条边

// --- A) SourceDisabled ---
auto group_d = ToolGroup::Create("S09b_Disabled");
auto* acq  = group_d->AddTool(registry.Create("fake_acq", "Acq"));
auto* pass = group_d->AddTool(registry.Create("fake_passthrough", "Pass"));
group_d->AddOutput("Image", TypeDesc{Type::ImageGray8, {}});
group_d->Link(acq, "OutputImage", pass, "InputImage");
group_d->LinkToOutput(pass, "OutputImage", "Image");
group_d->SetDisabled("Acq", true);  // 流级 disabled 集合（§4.3）；工具级 enabled 开关语义相同
DiagnosticList ddiags;
assert(group_d->Validate(ddiags));  // 结构合法；禁用本身不必然 Validate 失败
RunSession sd(group_d);
RunResult rd = sd.Run();
// 期望：rd.ok() == false；diagnostics 含 DiagnosticCode::SourceDisabled；
// Pass 不得假成功交出 Image；下游不得读到「假装有效」的帧（TC-LNK-06）

// --- B) InvalidBinding（主断言）---
auto group_b = ToolGroup::Create("S09b_BadBind");
auto* c = group_b->AddTool(registry.Create("fake_constant", "C"));
group_b->AddOutput("Out", TypeDesc{Type::Int32, {}});
// 端点缺失：属性名不存在 / 方向非法（输出←输出、输入→输入）/ 残缺 link
// Link 单边检查：失败即返回 LinkResult{ok=false}，不留下半条边（§7.4.2）
LinkResult bad = group_b->LinkToOutput(c, "NoSuchProp", "Out");
assert(!bad.ok);
// 或：Load("fixtures/invalid_binding.avtg") 后 Validate（AppendRawLink 不做边验证）
DiagnosticList bdiags;
bool ok = group_b->Validate(bdiags);
assert(!ok);
assert(std::any_of(bdiags.begin(), bdiags.end(), [](const Diagnostic& d) {
  return d.code == DiagnosticCode::InvalidBinding
      && d.severity == Severity::Error;
}));
// 不留下半条边；与 TypeMismatch / OrderViolation / Encapsulation 分码

// --- A) IoFailure（对应 tests/contracts_serialize.cpp TC-SER-07）---
LoadResult truncated = LoadAvtg("fixtures/truncated.avtg", registry);
assert(truncated.group == nullptr);
// truncated.diagnostics 含 DiagnosticCode::IoFailure（Severity::Error）
// 对照：未知 type → UnknownTypeId；过高 schema → SchemaTooNew；本项为 IO/截断

// SaveResult s = SaveAvtg(*group, "/root/no_write/out.avtg");  // 不可写路径
// 期望：s.ok == false；s.diagnostics 含 IoFailure

// --- B) 停相机 ≠ 自动 Cancel（停止矩阵独立步骤；对应 tests/smoke_acquisition_stop.cpp）---
auto group = ToolGroup::Create("S09c_StopCam");
auto* slow = group->AddTool(registry.Create("fake_cancel_check", "Slow"));
// … 合法最小链 …
RunSession session(group);  // 构造吃 std::shared_ptr<ToolGroup>
vyntek::imaging::AcquisitionSession camera;
camera.Arm("cam"); camera.Start();
// 线程1：RunResult r = session.Run(); // 在途
// 宿主：camera.RequestStop();  // 采集层；见 camera-acquisition / session-lifecycle
// 期望：session **未**被自动 RequestCancel；r 可跑至工具边界正常结束（或宿主再显式 Cancel）
// 诊断：不得仅因停相机而出现 Cancelled（除非宿主显式既停采集又 RequestCancel，TC-SESS-05）

// 示意：两子组先各自 Validate，再经 NestedGroupTool 包装放进外层列表并链终端（§9.2）
auto locate = ToolGroup::Create("Locate");
// … AddTool fake_acq → passthrough；AddOutput FixturedImage / Pose（示意）…
DiagnosticList ldiags;
assert(locate->Validate(ldiags));

auto defect = ToolGroup::Create("Defect");
defect->AddInput("Image", TypeDesc{Type::ImageGray8, {}});
// … 内部 fake 检测；AddOutput OkNg / DefectCount …
DiagnosticList ddiags;
assert(defect->Validate(ddiags));

auto job = ToolGroup::Create("Job");
// ToolGroup 不能直接 AddTool；每个子组包一层 NestedGroupTool（镜像其终端为端口）
auto loc_wrap = std::make_unique<NestedGroupTool>("loc", locate, "Locate");
loc_wrap->SyncTerminalsFromInner();
auto* loc = job->AddTool(std::move(loc_wrap));
auto def_wrap = std::make_unique<NestedGroupTool>("def", defect, "Defect");
def_wrap->SyncTerminalsFromInner();
auto* def = job->AddTool(std::move(def_wrap));
job->Link(loc, "FixturedImage", def, "Image"); // 便捷重载：工具端口 → 工具端口
// 可选：Pose 终端同理
job->AddOutput("DefectCount", TypeDesc{Type::Int32, {}});
job->LinkToOutput(def, "DefectCount", "DefectCount");

DiagnosticList jdiags;
assert(job->Validate(jdiags));
RunSession s(job);
RunResult r = s.Run();
// 期望：执行序 Locate → Defect；r.ok()；终端赋值生效；无环边

// 与本仓 tests/smoke_output_inspector.cpp 同一形状；对齐 output-inspection T10
using namespace vyntek::toolgroup;
using namespace vyntek::imaging;

ImageOutputInspector inspector;   // 默认 KeepLatest
std::vector<OutputCollectionEvent> events;
auto sub = inspector.SubscribeCollectionEvents(
    [&](const OutputCollectionEvent& ev) { events.push_back(ev); },
    /*replay_latest=*/false);      // true = 先重放当前保留集（含 EmptySnapshot）

ImageOutputItem item;
item.port_name   = "out";
item.image_index = 0;
item.buffer      = ImageBuffer::Rent(32);
const BufferId first_id = item.buffer.buffer_id();

// --- A: KeepLatest ---
std::vector<ImageOutputItem> items;
items.push_back(std::move(item));
inspector.PublishSuccess("run1", "toolA", "inv1", std::move(items));
// 非空成功 → SnapshotReplaced；当前集合可打开
ImageOutputKey key;  ImageBuffer opened;
inspector.TryOpenLatestOutput("toolA", "out", 0, key, opened);  // opened.buffer_id() == first_id

// 空成功 → 必须 EmptySnapshot（禁静默）
inspector.PublishSuccess("run2", "toolA", "inv2", {});

// 失败不替换上次成功快照（TC-OUT-05）
inspector.PublishFailure("run3", "toolA", "inv3");  // 保留仍在；不发 SnapshotReplaced

// 保留/拷贝失败 → Unavailable（不得把旧集合冒充本轮新结果）
inspector.NoteUnavailable("run4", "toolA", "inv4");

// Evict + 查看者寿命：已打开的 Share 仍有效；新 Open 对新身份不可用（TC-OUT-07）
ImageBuffer held = opened;   // 模拟已开查看者
inspector.Evict("toolA");
// held 仍可用至自行关闭；TryOpenLatestOutput 对新身份返回 false

sub.Unsubscribe();  // 只释放订阅，不清空已保留的最近输出（KeepLatest）

// --- B: ReleaseAfterRouting ---
inspector.SetRetentionPolicy(OutputRetentionPolicy::ReleaseAfterRouting);
// 发布后即不保留；再 Subscribe 无法补取已回收历史

// 与本仓 tests/smoke_acquisition_stop.cpp / smoke_memory_handoff.cpp 同一形状
using namespace vyntek::imaging;

AcquisitionSession session;
session.Arm("fake-cam");
session.Start();                       // state() == Running
FakeCameraAdapter adapter;

// --- A: 持帧 ImportNative（TC-ACQ-01）---
// PublishFrame(HoldFrameImport) = ImportNative(ReadOnly) + TryPostOwned；
// SDK release 恰好一次，且只在最后句柄关闭时发生（sdk_release_count()）
adapter.PrepareSlot(64, 0xAB);
adapter.PublishFrame(session, FakeCameraAdapter::Mode::HoldFrameImport);
assert(adapter.import_native_count() == 1 && adapter.slot_held());

// --- B: 回调内 Copy（TC-ACQ-02）---
// 先查入口/池预算（CanRent）→ TryRent → Copy-into → TryPostOwned；满则不拷直接拒绝；
// SDK 槽位立即归还（slot_returned()），回调内不得等归还（AssertCallbackNonBlocking）
adapter.PublishFrameFromCallback(session, FakeCameraAdapter::Mode::CallbackCopy);
assert(adapter.copy_count() == 1 && adapter.slot_returned());

// --- C: Latest 预览（TC-ACQ-06）---
for (int i = 0; i < 10; ++i) { adapter.PublishFrame(session, FakeCameraAdapter::Mode::HoldFrameImport); }
auto latest = session.Latest();        // 有所有权预览槽：只留最新；替换即关上一预览
auto front  = session.PeekIngressFront();  // FIFO 队首；与 Latest 分槽，禁混淆
assert(session.ingress_size() <= 8);   // kIngressCapacity = 8；满 → InvalidOperation

// --- D: 停流结束条件（TC-SESS-01）---
session.RequestStop();                 // → Quiescing → … → Stopped
StopSummary summary;
session.WaitStop(StopTimeout{1000}, &summary);
assert(session.state() == AcquisitionState::Stopped);
// 结束联合条件：无新回调、队列空、会话拥有引用已关、SDK 归还完成（stop_progress）

// --- E: 外保留 ≠ 假称已归还（TC-SESS-02）---
auto exported = latest;                // 会话外仍持有（外部保留）
// stop_progress().external_retention 为 true；claims_device_returned() 不得为 true

// --- F: 超时续清（TC-SESS-03）---
StopSummary to;
session.WaitStop(StopTimeout{50}, &to);  // 超时返回未排空；cleanup_continues，不假装 Stopped

// --- G: ReturnFailed / 断线可观察（TC-SESS-04）---
session.SetReturnFailedCountForTest(1);  // 或 session.NoteCameraDisconnected()
// stop_faults() 可观察；不自动再 Release；泵继续其他项；停止结果汇总

// --- H: 两端都停（TC-SESS-05）---
// 宿主要相机与 Run 一起停：必须显式，两端互不代停（M3-07 / TC-SESS-05）
session.RequestStop();
run_session.RequestCancel();           // 显式 Cancel；RunSession 不会替你停采集
// 禁止假设一次 SDK.Stop = 三层全停

// 与本仓 tests/smoke_memory_pool.cpp / smoke_memory_ownership.cpp /
//          smoke_memory_grants.cpp / smoke_memory_handoff.cpp 同一形状
using namespace vyntek::imaging;

// --- A: 工厂接管 ---
auto rented = ImageBuffer::Rent(4096);            // TC-MEM-01 成功接管（失败则空，不半建实体）
auto rented2 = ImageBuffer::TryRent(4096);        // 复制前预算路径（M4-03）
assert(ImageBuffer::CanRent(4096));                // 非预留查询，总在 TryRent 之前
// TakeOwnership 抛错路径：owner 仍由调用方释放（TC-MEM-02）
// ImportNative 抛错路径：不调 release（TC-MEM-03）

// --- B: 最后引用 ---
auto h1 = rented.Share();
auto h2 = rented.Share();
h1 = ImageBuffer{};                                // 关掉一个 Share；仍 Active（TC-MEM-04）
// 关闭全部 handle + 访问 + 排队申请后才 Returning
// 禁止：持最后引用边 AwaitReturnCompleted（TC-MEM-05，否则卡死）

// --- C: pin（pin 在 View/像素句柄层，不在 ImageBuffer 上）---
Gray8Handle gh{PixelImage::RentGray8(ImageInfo(32, 16))};
auto rview = gh.OpenRead();                        // OpenResult<ReadOnlyViewBase>
ImageBufferPin pin = rview->Pin();                 // 读 pin：父 reader close 后仍阻写/归还（TC-MEM-06）
assert(pin && pin.access() == BufferAccess::ReadOnly);
rview->close();                                    // pin 仍阻写/归还；Access 永 ReadOnly
pin = ImageBufferPin{};                            // 释放读 pin

auto wview = gh.OpenWrite();                       // OpenResult<WritableViewBase>
ImageBufferPin wpin = wview->Pin();                // 写 pin
// wview->Complete() 在写 pin 未放时 → 抛 std::runtime_error（TC-MEM-07）
wpin = ImageBufferPin{};                           // 释放写 pin
wview->Complete();                                 // 现在可 Complete

// --- D: 授予/取消与 Share/Dispose ---
// OpenRead/OpenWrite + CancelToken；发起 handle Dispose 不撤已入队申请（TC-MEM-08）
// Share 与 Dispose 竞争：成功子对象独立有效（TC-MEM-09）

// --- E: 初始化 / Invalid ---
{
  Gray8Handle h{PixelImage::RentGray8(ImageInfo(32, 16))};
  auto w = h.OpenWrite();
  w->close();                                       // 未 Complete → Invalid（TC-MEM-10）
  auto bad = h.OpenRead();
  assert(!bad && bad.status == Status::Invalid);
}
// 类型化首次仅写 ROI → 拒绝；ROI 中止 → 整实体 Invalid（TC-MEM-11）
// Invalid 后带 expectedVersion 的 OpenWrite 拒绝；无期望版本完整写可恢复（TC-MEM-12）

// --- F: 归还隔离 ---
// 两实体并行归还；其一 releaseAsync 卡住/失败
// expect：恰好一次 release；不串行堵另一项；ReturnFailed 不自动重试、不回池（TC-MEM-13）

// 与本仓 bindings/csharp/Vyntek.Controls/ImageDisplay.cs 同一形状（对齐 image-display / TC-DISP-*）
// 像素已由绑定层从 C++ 句柄投影为 IPixelImage

var update = viewer.SetImage(image);   // TC-DISP-01：登记+Share；未承诺已 OpenRead
// 调用方随后可关闭自有 handle；控件不接管（TC-DISP-02）

var retain = viewer.SetImage(rwImage, InputRetention.RetainInput);  // 默认即 RetainInput
// 原地写须等读者退出（TC-DISP-03）

var snap = viewer.SetImage(rwImage, InputRetention.Snapshot);
await snap.Completion; await snap.InputReleased;  // 释放后原图可写；屏幕可仍旧图（TC-DISP-04）
var detach = await retain.DetachInputAsync();     // Released 或 CpuBudgetExceeded 不毁当前（TC-DISP-05）

// Completion / InputReleased / ImageRendered / ReturnCompleted 分别断言，互不等价（TC-DISP-06）
// ImageRendered 由宿主 NotifyImageRendered(updateId) 上报；控件不冒充（TC-DISP-06）
// 注入 VersionMismatch / UnsupportedImage → Failed，旧画面保留（TC-DISP-07）

viewer.SetImage(gray);  viewer.TryGetGray8(x, y, out var g);    // 仅相符格式成功（TC-DISP-08）
viewer.SetImage(rgb);   viewer.TryGetRgb24(x, y, out var r2);   // 无隐式转换
viewer.SetImage(bgr);   viewer.TryGetBgr24(x, y, out var b);
viewer.SetImage(depth); viewer.TryGetDepth16(x, y, out var d);  // 含 out_is_valid

viewer.TryGetGray8AtView(viewX, viewY, out var p); // ROI/负步长→逻辑坐标（TC-DISP-09）

viewer.Unload();                          // 卸载 → 取消候选；保留 Source（TC-DISP-10）
var again = viewer.Remount();             // 重挂载仍有效；Source = 新请求
viewer.CpuBudgetLimitBytes = 4 << 20;     // 预算不足 → Failed + 保留旧图（TC-DISP-11）

// Dispose / ClearImageAsync → 不停 Run、不停相机（TC-DISP-12 / TC-CTL-05）