ToolGroup
vyntek/toolgroup.hpp 转发嵌套 <vyntek/toolgroup/…>。规格全文：toolgroup。NON-STABLE / STUB（真实算法 stub；编排核心语义已实现）。
头文件 → 关键公开符号（按实）
| 头 | 关键公开符号 | 状态 |
|---|---|---|
toolgroup/toolgroup.hpp | ToolGroup · Create / Load（static）· AddTool / RemoveTool · AddInput / AddOutput · Link（3 重载）· LinkToOutput / LinkFromInput · Unlink · AppendRawLink · Validate（2 重载）/ ValidateLink · SetDisabled / IsDisabled / disabled() · abort_on_tool_failure · component_version · retained_fields · Asset（assets() / AddAsset / ClearAssets）· tools() / links() / inputs() / outputs() · FindTool · MakeRunSession · ResolveEndpoint · kGroupTerminalOwner（"group"） | 核心语义已实现（Run/Link/Validate、.avtg Load/Save）；真实算法仍 stub |
toolgroup/run_session.hpp | RunStatus（Idle / Running / Succeeded / Failed / Cancelled / Busy）· RunResult（status / diagnostics / ok() / failed_tool_id / message）· RunSession：SetInput（typed + 字面量重载）· Run · GetOutputValue / GetOutput<T> / GetOutput（string 投影）· ResetOutputs · LastResult · RequestCancel / cancel_requested · SetRunProbe / run_probe_count / ClearRunProbe · SetToolWorkDoneHook / has_tool_work_done_hook / ClearToolWorkDoneHook（联合停流门，DEBT-IMG-004） | 已实现；GetOutput 标量投影（图像句柄无字符串形式故返回空串），≠ KeepLatest 保留集 |
toolgroup/tool.hpp | LastRunStatus（NeverRun / Succeeded / Failed / Cancelled / Skipped）· Tool：AddInput / AddOutput / DeclareProperty · SetProperty / GetProperty · AssignPort（执行器赋值，绕过 host-writable）· ReadPort · HasPort / HasEndpoint · retained_fields（§6.5）· 虚 Run(RunContext&) | 外形在；基类 Run 报 NotImplemented（真实算法 Reed） |
toolgroup/terminal.hpp | Type（闭集 20 值：Bool / Int32 / Int64 / Float32 / Float64 / String / ImageGray8 / ImageRgb24 / ImageBgr24 / ImageDepth16 / Point2d / Line2d / Circle2d / Rect2d / Affine2d / Pose2d / Region / Fixture / RunStatus / Enum）· TypeDesc（type + enum_id）· TerminalDirection（In / Out）· Terminal | 外形在 |
toolgroup/link.hpp | LinkId（= string）· LinkEndpoint（tool_id + terminal_or_path）· Link（id / source / target）· LinkResult（ok / link_id / diagnostics） | 外形在 |
toolgroup/value.hpp | 几何/语义字段：Point2d / Line2d（两端点持久形态）· Circle2d / Rect2d / Affine2d（2×3 行主序）/ Pose2d / Region / Fixture · RunStatusValue（Ok / Ng / Failed / Skipped，≠ 编排 RunStatus）· EnumValue · Value（Bool / Int32 / Int64 / Float32 / Float64 / Str / Point / Line / Circle / Rect / Affine / Pose / Reg / Fix / RunStat / Enum / Image / EmptyOfType 工厂；empty / type / type_id / payload；As* 无隐式转换；TryConvertTo 白名单前向数值加宽）· TypeToString / TypeFromString / TypesAreLinkable | 外形在；图像载荷为 PixelImageHandle（非像素拷贝） |
toolgroup/property_bag.hpp | PropertyFlags（required / persistable / writable / linkable）· PropertyDesc · PropertyResult / PropertySetResult · PropertyBag：Declare / Has / Find / GetType / Get / Set / Assign（绕过 writable，执行器路径）/ MissingRequired / properties() / ClearRuntimeValues | 外形在 |
toolgroup/run_context.hpp | ToolId（= string）· RunContext（cancel_requested + trace_id） | 外形在 |
toolgroup/diagnostic.hpp | Severity（Error / Warning / Info）· DiagnosticCode 闭集 14 值：TypeMismatch / OrderViolation / Encapsulation / Busy / UnknownTypeId / SchemaTooNew / IoFailure / SourceDisabled / InvalidBinding / MissingRequiredProperty / Aborted / Cancelled / NotImplemented / ToolFailure（末位追加；工具自身算法失败，≠ NotImplemented）· Diagnostic（code / severity / message / tool_id / path / link_id）· DiagnosticList | 编排码表；不是资源快照 |
toolgroup/serialize.hpp | LoadResult（group + diagnostics）· SaveResult（ok + diagnostics）· LoadAvtg / SaveAvtg · kAvtgSchemaVersion = 1 | .avtg Load/Save 已实现（JSON、schema 门禁、未知 type_id、IoFailure、未知字段保留；TC-SER-01…07 覆盖） |
toolgroup/registry.hpp | ToolFactory · ToolRegistry：Register（重复 type_id 拒绝且不覆盖）· Contains · Create（未知 type_id → nullptr → UnknownTypeId）· TypeIds（排序）· RegisterBuiltinTools | 内置工具目前只有 passthrough 骨架（src/toolgroup/registry.cpp：基类 Run 报 NotImplemented，作注册契约夹具） |
toolgroup/output_inspector.hpp | RunId / InvocationId（string）· OutputCollectionEventKind（SnapshotReplaced / EmptySnapshot / Unavailable / Evicted）· OutputRetentionPolicy（KeepLatest / ReleaseAfterRouting）· OutputCollectionEvent · ImageOutputKey / ImageOutputItem · OutputSubscription（RAII 退订）· IImageOutputInspector 接口 + ImageOutputInspector 实现：SetRetentionPolicy · PublishSuccess / PublishFailure · NoteUnavailable · Evict · TryOpenLatestOutput / TryOpenOutput · SubscribeCollectionEvents（replay_latest） | T10 事件与 KeepLatest 外形在；未验收；观察不驱动 Run（TC-OUT-09） |
toolgroup/nested_group_tool.hpp | NestedGroupTool（kTypeId = "nested_toolgroup"；inner_group() · 虚 Run 跑内层完整列表 · SyncTerminalsFromInner）· RegisterNestedGroupTool | 外形在 |
toolgroup/fake_tools.hpp | FakeAcq / FakePMAlign / FakePassthrough / FakeCloneWrite / FakeFailOnce / FakeFailAlways / FakeConstant / FakeCancelCheck · fake::register_fake_tools(ToolRegistry&) | 测试/示例假工具（独立注册；非 RegisterBuiltinTools 内置） |
名称辨析
| 名称 | 含义 |
|---|---|
toolgroup::RunStatus（编排状态机） | Idle / Running / Succeeded / Failed / Cancelled / Busy，≠ RunStatusValue（业务结果值 Ok/Ng/Failed/Skipped） |
toolgroup::Diagnostic | 编排诊断码表 |
| performance-and-diagnostics | 资源快照 ResourceDiagnosticsSnapshot（hold_duration 微秒，实体 born_at 起算，在 imaging 侧） |
| output-inspection | 最近输出观察 |