@international-iot-association/plugin-contracts

Station-shell 与插件之间协议的唯一真源（types-only，零运行时依赖）。

ChannelCallOptions / ChannelControlRequest 是插件运行时与Shell IPC共用的具名通道请求类型。 读写资源守卫和关闭资源守卫只在本包声明，宿主不得维护丢字段的平行副本；本次提取不改变运行时权限或设备命令。 属于组 A · 协议锁步组（与 plugin-sdk/api-bridge/rct-state 一起随 agentApi major 锁步发布）。

可选普通二进制缓冲

TCP 通道的 ChannelStatus 可返回 tcpConnectionGuardRevision: 1 和 tcpConnectionGeneration。ChannelCallOptions 与 open/status/close 的 ChannelControlRequest 可携带 requireTcpConnectionGeneration: string， 经 Shell 转交同一 Agent/provider 核验；省略保持旧调用行为。调用方必须先探测能力， 不得把连接名或 endpoint 当作代次证明。当前同配置重开换代及 TRV 强制消费仍在集成验证， 公开字段存在不代表生产已准入。

私有raw-text可探测 privateResponseWindowRevision: 1，用 ChannelCallOptions.privateResponseWindow 在ACK响应完成时同步建立空私有窗口，再返回窗口ID；原ACK不复制入窗口，之后数据不等待插件再次begin。 仅明确raw-text/expectResponse/私有资源guard可用；容量、超时、取消和清理契约见API reference。 新增可选privateResponseWindowReceiptRevision: 1：调用方在窗口options附带UUID requestId， 宿主回传同请求/资源身份及opened或ack-timeout结果；只有原生写回调已成功、当前任务到期且无ACK/无窗口时， 才返回无窗口超时回执。异常Promise不等于该回执，不授权重发；未附requestId的旧请求行为不变。

普通Modbus串口可探测 serialEventFenceRevision: 1，经 serial-event-fence 的begin/end 显式标记订阅事件来源。启用期间事件增加宿主生成的 serialEventOrigin，含revision、resourceId、fenceId； 未启用及end后事件形状不变。该能力只标记Agent解析边界，不排空串口，不替代CRC或运行方的过滤； 完整请求、单attachment限制与迟到帧边界见API reference。

串口关闭另由 ChannelStatus.serialCloseGuardRevision: 1 探测； channels.control({ action: 'close', logicalName, requireSerialResource: { revision: 1, resourceId } }) 在Agent生命周期锁取得后、detach/原生close前同步核对预期资源和attachment；拒绝不清除使用记录。 已closed且无打开附件的预配置资源允许幂等关闭，仍执行私有资源归属检查。 这是资源ID边界，不是同资源重开generation、事件隔离、配置冻结或物理独占保证。

串口发送资源守卫由 ChannelStatus.serialResourceGuardRevision: 1 探测；每次携带 requireSerialResource: { revision: 1, resourceId }，Agent在入队与发送前校验资源/绑定/attachment， 并快照守卫避免排队期间被改写。不提供租约、事件隔离或关闭/恢复保证；无能力字段必须拒绝依赖该特性的执行。

普通raw-text仪器的Agent内消费缓冲由 ChannelStatus.rawBinarySessionRevision: 2 探测， 经宿主保留 raw-binary-session payload进行begin/read/flush/write/end；write也绑定session/resource， 早期revision 1不提供受保护写入，不能降级成普通纯写。仅单一attachment可用， 不提供隐私、物理排空或崩溃恢复保证；日志/订阅仍照常广播，不能传DUT材料。完整条件见 API reference。缺少能力字段时不得假定宿主支持。

可选私有串口流量

私有接收窗口由 ChannelStatus.privateWindowRevision: 1 探测，使用宿主保留 writeRead payload kind: 'private-raw-window' 的begin/read/close操作及逐请求resource guard。 begin确认后才触发设备；无TX、无广播，read返回累计文本。窗口限时/限容量失败后须显式关闭， 不允许降级成订阅或伪CLI。精确字段和安全边界见下方API参考。

可选串口流量策略 SerialChannelConfig.trafficPrivacy='private'，须检查 ChannelStatus.trafficPrivacy 同值回执（旧宿主无回执必须拒绝敏感IO）。它关闭资源日志与所有事件广播， 还须确认 privateTrafficRevision: 1，每次写入携带 requirePrivateTraffic: { revision: 1, resourceId }， 由宿主在请求准入时校验当前私有资源，避免状态检查后重启的时序缺口。仅有旧privacy回执仍不可发送材料。 仅向Agent注入的所有者runtime返回原始响应，响应中的request为null；详情与不可降级/重启限制见 API参考。默认通道语义不变，尚非生产准入声明。

可选持久排他创建

PluginStorage.claimDurable?(fileName, content) 是向后兼容的可探测能力；旧宿主缺方法时， 依赖制造写前意图的插件必须在设备IO前拒测，不得回退到 write/append。 只接受根目录单文件名（字母数字开头，其后字母数字、点、下划线、连字符，总长≤181）， UTF-8内容≤16KiB；采用排他创建，不覆盖已有文件。返回 created 前完成文件fsync、 目录fsync及关闭；祖先目录链也同步，避免并发mkdir尚未确认的目录项。 已有文件仅当内容逐字匹配，并再次fsync文件和目录后才返回 exists，否则抛错； 这样绑定索引被另一进程抢先创建但尚未同步时，也不能未经持久确认就进入新步骤。 调用者仍须保守视作已有意图，绝不能凭exists发送第二次写命令。 创建后错误保留文件（可能为空/部分内容）；禁止自动删除并重建。 不支持目录同步的系统/文件系统直接失败（包括尚未验证的Windows路径），不能宣称断电恢复保障； 尚未有Windows/产线断电证据。普通 write/append/remove 语义不变，不受此能力保护， 插件必须独占其制造记录命名空间且不得用普通API修改这些记录。此API不是分布式租约或通用事务。