feat: 增加控制消息 Trace 元数据

CHANGELOG.md

@@ -21,6 +21,10 @@
 
 ### 新增
 
+- 增加独立 <code>SecsFrame-ControlTrace/1</code> 信封，对公共未认领控制
+  事件提供不含 Body 的十字节头元数据导出与严格读取。
+- 控制记录保留方向、观察状态和原始头字段，允许未知非零 SType 往返；增加
+  未匹配 Reject 黄金向量、Data Message 拒绝、畸形字段与资源限制测试。
 - 增加独立 <code>SecsFrame-DiagnosticTrace/1</code> 信封，为公共
   <code>HsmsDiagnostic</code> 提供确定性受限字段快照导出与严格读取。
 - 诊断快照只保留代码、层级、操作、状态、计时器和可选协议标量，明确排除

README.md

@@ -43,8 +43,9 @@ Equipment 应用发送策略的 Collection Event、报警目录查询、单报
 不进入线上通讯路径。
 <code>SecsFrame.Trace</code> 在该文本层上提供版本化的数据消息 Trace 信封、
 严格的 Item 路径脱敏、显式 allowlist 重放，以及默认关闭的缩放/封顶时序
-重放；独立诊断信封只保存稳定标量，不保存异常或原始帧。该包不会接管连接
-事件消费者，也不会复用原事务标识。
+重放；独立诊断信封只保存稳定标量，不保存异常或原始帧；控制信封可保存
+未认领公共控制事件的十字节头元数据。该包不会接管连接事件消费者，也不会
+复用原事务标识。
 Item 用法与边界见
 [docs/SECS-II-ITEMS.md](docs/SECS-II-ITEMS.md)，消息集成见
 [docs/SECS-MESSAGES.md](docs/SECS-MESSAGES.md)，传输适配边界见

docs/ARCHITECTURE.md

@@ -19,6 +19,8 @@ Trace 的时序重放必须显式启用，只在允许发送记录之间等待
 发送 API 创建新事务；默认重放不引入时间等待。
 结构化诊断使用独立只读快照信封：只复制公共诊断的稳定标量，明确排除原
 异常和未解码帧，也不能进入重放路径。
+控制消息使用另一个只读元数据信封，只从调用方已消费的公共未认领控制事件
+复制十字节头字段；它不增加内部控制面观察者，也不代表完整握手抓包。
 
 ## 核心原则
 
@@ -169,6 +171,7 @@ HSMS 头 Session ID 与 System Bytes。没有 W-Bit 的出站消息在写出后
 - `SecsFrame.Trace` 依赖 `SecsFrame.Sml` 与 `SecsFrame`，重放必须回到
   公共发送 API，不得直接构造或写出保留旧事务标识的线上帧；可选时序只
   控制相邻发送前的等待，不得绕过连接状态、T3 或显式 allowlist。诊断
-  导出不得隐式包含 <code>Exception</code> 或 <code>HsmsFrame</code>。
+  导出不得隐式包含 <code>Exception</code> 或 <code>HsmsFrame</code>；控制
+  元数据导出不得包含 Body 或隐式订阅连接事件流。
 - 核心包不得依赖 GEM、SML/SMN、依赖注入容器或具体日志实现。
 - 状态机计时使用可替换的时间抽象，测试不得依赖真实长时间等待。

docs/HSMS-CONNECTION.md

@@ -83,6 +83,12 @@ var secondary = await connection.SendAsync(
 - <code>ControlMessageReceived</code>：未被当前控制或数据事务认领的帧；
 - <code>DataMessageDecodeFailed</code>：原始帧和严格解码错误。
 
+调用方在自己的事件循环中可以使用
+<code>SecsTraceControlRecord.CreateReceived</code> 对
+<code>ControlMessageReceived</code> 创建不含 Body 的头元数据快照。该事件
+不包含已被内部 Select、Linktest、Deselect 或数据事务认领的控制消息，
+因此快照不是完整控制面抓包。格式与安全边界见 [TRACE.md](TRACE.md)。
+
 带错误的状态事件和解码失败事件还会提供可选
 <code>HsmsDiagnostic</code>，用于按稳定代码、层级、操作与计时器处理，
 无需解析异常消息。调用任务抛出的异常可通过

docs/ROADMAP.md

@@ -100,7 +100,8 @@ E30-0526 材料。下一可执行优先级已转入阶段 3；SML 调试读写
 公共发送 API 创建新事务，不复用旧会话或 System Bytes。可选时序重放也已
 完成：只使用允许发送记录的相邻时间戳，支持显式加速和缩放后单次等待封顶，
 默认重放仍不等待。结构化 HSMS 诊断现可通过独立受限信封导出；快照只包含
-稳定标量，明确排除异常和原始帧。
+稳定标量，明确排除异常和原始帧。现有公共未认领控制事件也可导出不含 Body
+的十字节头元数据，同时保持未知非零 SType 的原始值。
 
 ## 阶段 3：元数据与工具
 
@@ -110,12 +111,14 @@ E30-0526 材料。下一可执行优先级已转入阶段 3；SML 调试读写
 - [x] 已解码数据消息的 Trace 导出、结构化脱敏和受控重放基线。
 - [x] 显式启用、可缩放且单次等待封顶的 Trace 重放时序。
 - [x] 不包含异常与原始帧的受限结构化诊断 Trace 导出和严格读取。
-- 控制消息和故障原始样本等互操作诊断扩展。
+- [x] 公共未认领控制消息的受限头元数据 Trace 导出和严格读取。
+- 完整控制面观测和故障原始样本等互操作诊断扩展。
 
 当前 Trace 基线不接管连接事件流，也不把原始标识写回线上。时序重放默认
 关闭，并继续经过显式 allowlist 与公共发送 API。诊断快照始终排除
-<code>Error</code> 与 <code>Frame</code>。后续控制与故障原始样本扩展必须先
-定义原始字节的数据分级、默认不导出策略和可验证脱敏边界。
+<code>Error</code> 与 <code>Frame</code>。控制元数据只覆盖应用事件循环已经
+取得的未认领控制帧，不声称观察内部握手。后续完整控制观测与故障原始样本
+扩展必须先定义原始字节的数据分级、默认不导出策略和可验证脱敏边界。
 E173 SMN 与 E172 SEDD 仍需先核对授权标准及允许分发的 Schema/表示形式。
 
 ## 发布门槛

docs/TRACE.md

@@ -8,10 +8,12 @@
 - 按 Stream、Function 与 Item List 路径执行的结构化替换脱敏；
 - 只选择显式允许的本地发送记录，并通过正常公共发送 API 串行重放；
 - 可选按缩放且封顶的源时间间隔执行受控时序重放；
-- 不包含异常和原始帧的结构化 HSMS 诊断快照导出与严格读取。
+- 不包含异常和原始帧的结构化 HSMS 诊断快照导出与严格读取；
+- 公共未认领控制事件的十字节头元数据导出与严格读取。
 
 当前切片不是原始网络抓包器，不记录 TCP 字节、transport Session generation、
-控制帧或异常对象，也不会接管 <code>HsmsConnection</code> 的单消费者事件流。
+控制帧的线上原始字节或异常对象，也不会接管 <code>HsmsConnection</code> 的
+单消费者事件流。
 应用应在自己的事件循环中从 <code>HsmsIncomingDataMessage</code> 创建接收记录，
 并在调用发送 API 前显式创建发送记录。
 
@@ -88,6 +90,38 @@ Session ID、System Bytes、远端状态字节和被拒绝的 SType。枚举只
 与 <code>SecsFrame-Trace/1</code> 消息信封相互独立，不能交给重放器。协议
 标识和状态字节仍是运维元数据；存储和共享文件时仍需执行访问控制与保留策略。
 
+## 未认领控制消息元数据
+
+应用在自己的连接事件循环中可以对
+<code>ControlMessageReceived</code> 创建只包含头字段的快照：
+
+~~~csharp
+if (connectionEvent.Kind == HsmsConnectionEventKind.ControlMessageReceived)
+{
+    var record = SecsTraceControlRecord.CreateReceived(
+        DateTimeOffset.UtcNow,
+        connectionEvent);
+    var text = new SecsTraceControlCodec().Encode(new[] { record });
+}
+~~~
+
+独立信封固定使用 LF 与 10 个单空格分隔字段：
+
+~~~text
+SecsFrame-ControlTrace/1
+Control 2026-08-29T05:00:00.0000000Z Received Selected 65535 0x05 0x03 0x00 0x07 0x10203040
+~~~
+
+字段依次为 UTC 时间、本地方向、观察到的会话状态，以及原十字节 HSMS 头的
+Session ID、Header Byte 2、Header Byte 3、PType、SType 和 System Bytes。
+字节字段使用固定宽度大写十六进制。SType 以原始字节保存：<code>0x00</code>
+因表示 Data Message 而拒绝，未知非零值允许严格往返，便于保留互操作证据。
+
+控制帧按核心模型不能携带 Body，快照类型也没有 Body 字段。当前公共事件只
+转发未被 Select、Linktest、Deselect 或数据事务认领的控制帧，主要用于未匹配
+Reject；这个工具不会订阅内部状态机，也不是完整控制面抓包。控制信封不能
+进入消息重放器，头字段仍应按运维元数据执行访问控制与保留策略。
+
 ## 结构化脱敏
 
 脱敏发生在不可变 Item 树上，而不是对 SML 文本做字符串替换：
@@ -179,4 +213,5 @@ var results = await new SecsTraceReplayer().ReplayWithTimingAsync(
 测试还验证重新分配 Session ID/System Bytes 并获得新 Secondary。它证明
 当前工具组合边界，不代表设备命令安全性或 SEMI 一致性认证。诊断信封另有
 黄金向量、可选字段往返、严格枚举/十六进制、资源限制及异常/帧内容不泄漏
-测试。
+测试。控制信封另有未匹配 Reject 黄金向量、未知 SType 往返、Data Message
+拒绝、严格字段与资源限制测试。