# 17-04 HAL Scope/Meter 结构化证据复核

## 定位

本文件落实 `ACC-029` 和 `INT-016`，只复核 `04基于Web的LinuxCNC兼容数控仿真平台.txt` 中与 HAL Scope/Meter 相关的条目：

- `4.13 HAL Scope`
- `4.14 HAL Meter`
- `10.7 HAL Scope`

严格口径：

1. LinuxCNC 原生 `halscope` 和 `halmeter` 是 HAL 工具，不是普通 Web 截图功能。
2. 浏览器不能声明运行了 LinuxCNC 原生 GTK/实时 HAL 工具，除非实际启动对应 native 工具并采集其输出。
3. Web 等效实现可以作为替代证据，但必须输出结构化 HAL sample、meter value 或 waveform evidence；截图只能作为 P5 辅助证据。

## LinuxCNC 源码证据

| 工具 | LinuxCNC 归属 | 关键行为 | 对 Web 的约束 |
| --- | --- | --- | --- |
| `halscope` | `src/hal/utils/scope.c`、`scope_rt.c`、`scope_shm.h`、`scope_usr.h`、`docs/src/hal/halscope.adoc`、`docs/src/man/man1/halscope.1.adoc` | 原生软件示波器，由用户态 GUI 和 `scope_rt` HAL 实时组件协作；通过共享内存、采样周期、record length、trigger、channel data 捕获 HAL pin/signal/parameter 波形 | Web 只能声明“等效 HAL waveform evidence”，不能把 canvas 折线或 UI 截图当作原生 `halscope` |
| `halmeter` | `bin/halmeter`、`docs/src/man/man1/halmeter.1.adoc` | 原生 HAL 万用表，用独立 HAL 连接观察单个 pin、signal 或 parameter 当前值 | Web 可用 virtual HAL registry/snapshot/readPin 等价覆盖当前值观察，但必须输出可复验 JSON |

源码级边界：

- `scope_rt.c` 导出 `scope.sample`，并维护 `IDLE`、`INIT`、`PRE_TRIG`、`TRIG_WAIT`、`POST_TRIG`、`DONE` 等采样状态。
- `scope_rt.c` 的采样逻辑按通道读取 HAL 数据地址，支持 bit/u32/s32/float 等数据宽度。
- `scope_shm.h` 固定了共享控制区，包括采样周期、记录长度、预触发、触发通道、触发电平、强制触发、当前样本、每通道 offset/type/len 等字段。
- `scope_usr.h` 记录用户态横轴、纵轴和通道选择状态，说明 `halscope` 不是单个静态数据点，而是有采样窗口和通道配置的波形工具。
- `halmeter.1.adoc` 将 `halmeter` 定义为观察 HAL pin、signal、parameter 的工具，行为接近单值仪表，不等价于 `halscope` 的波形缓存。

## 现有 Web/WASM 证据

| 项目 | 已有证据 | 可支撑内容 | 不足 |
| --- | --- | --- | --- |
| `wasm-port` | `tests/ui/node/verify_real_simulation_programs.mjs` | virtual HAL pin registry、bridge snapshot、runtime read/write、`spindle.0.speed-out`、`iocontrol.0.coolant-flood` 等当前值证据 | 可支撑 meter/status snapshot；不能单独支撑 `halscope` waveform |
| `wasm-port` | `runtime/opfs/snapshot-store.js` | OPFS session 中校验 `virtualHal.state.source === "browser-virtual-hal"`，并保存 virtual HAL 状态和诊断 | 证明状态可持久化；不证明固定采样周期、trigger 和多 sample 波形 |
| `web-rtcp-5axis-xyzbc-trt-sim-plan` | `tests/node/verify_gmoccapy_hal_model.mjs` | gmoccapy HAL model、pin groups、core/spindle/postgui nets、source compliance | 可支撑 HAL 模型和 UI 监视；不等价于原生 `halscope` 采样器 |

## 结构化 evidence 要求

### HAL Meter JSON

`4.14 HAL Meter` 和 `10.6 HAL 信号监视` 后续晋级至少需要输出如下结构，文件格式可为 JSON 或 JSONL：

```json
{
  "apiName": "hal_meter_evidence",
  "source": "browser-virtual-hal",
  "sampleTime": "2026-07-10T12:41:00Z",
  "items": [
    {
      "name": "spindle.0.speed-out",
      "sourceKind": "pin",
      "type": "float",
      "value": 1200,
      "writable": false,
      "signal": "spindle-speed"
    }
  ],
  "integrity": {
    "complete": true,
    "sourceReference": "linuxcnc/docs/src/man/man1/halmeter.1.adoc"
  }
}
```

验收规则：

- `items` 必须覆盖 pin、signal 或 parameter 中实际声称支持的类型。
- 每个 item 必须记录 `name`、`sourceKind`、`type`、`value`。
- 如支持写入或 UI 修改，必须记录 `writable`，并用 runtime read/write gate 证明写入后快照更新。
- 只显示 UI 数字、截图或 canvas 文本不构成 P3/P4 证据。

### HAL Scope Waveform JSON

`4.13 HAL Scope` 和 `10.7 HAL Scope` 后续晋级至少需要输出如下结构：

```json
{
  "apiName": "hal_scope_waveform_evidence",
  "source": "browser-virtual-hal",
  "samplePeriodNs": 1000000,
  "recordLength": 256,
  "channelCount": 2,
  "trigger": {
    "channel": 0,
    "edge": "rising",
    "level": 0.5,
    "forced": false
  },
  "channels": [
    {
      "index": 0,
      "name": "spindle.0.speed-out",
      "kind": "pin",
      "type": "float",
      "scale": 1,
      "units": "rpm"
    }
  ],
  "samples": [
    {
      "sampleIndex": 0,
      "timeNs": 0,
      "values": [0, false]
    }
  ],
  "sourceReference": {
    "linuxcnc": [
      "linuxcnc/src/hal/utils/scope_rt.c",
      "linuxcnc/src/hal/utils/scope_shm.h",
      "linuxcnc/docs/src/hal/halscope.adoc"
    ]
  }
}
```

验收规则：

- `samplePeriodNs`、`recordLength`、`channelCount` 必须非空且与 `samples` 数量一致。
- `channels` 必须记录每个通道的 HAL 名称、来源类型、HAL 数据类型和缩放信息。
- `trigger` 必须记录触发来源；如采用强制触发，必须显式 `forced: true`。
- `samples` 必须是可解析的结构化数组，不能只保存截图像素或 canvas polyline。
- Node gate 至少校验字段完整性、采样数量、时间单调、通道数量和值类型；Browser gate 可在此基础上验证 UI 渲染。

## 04 条目结论

| 04 项 | 复核结论 | 后续 gate |
| --- | --- | --- |
| `4.13 HAL Scope` | 条件通过目标。LinuxCNC 原生 `halscope` 是 RT/GTK 工具；浏览器当前只能按等效 waveform evidence 验收 | 新增 `hal_scope_waveform_evidence` JSON/Node gate；可选 browser canvas 只作为 P4/P5 补充 |
| `4.14 HAL Meter` | 条件通过。当前 virtual HAL pin registry/snapshot/read/write 能支撑 meter-like 当前值证据，但不是原生 GTK `halmeter` | 新增 `hal_meter_evidence` JSON/Node gate；覆盖 pin/signal/parameter 当前值 |
| `10.7 HAL Scope` | 待实现 gate。Web UI 的 HAL Scope 不能只凭截图晋级 | 新增 waveform JSON、字段校验、浏览器渲染 smoke 和 evidence 文件路径 |

## 最小验收命令建议

后续实现对应 gate 后，至少补入以下命令之一：

```bash
cd wasm-port && node tests/ui/node/verify_hal_meter_evidence.mjs
cd wasm-port && node tests/ui/node/verify_hal_scope_waveform_evidence.mjs
npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run evidence:web
npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run evidence:compare
```

若只是维护当前文档边界，继续使用本轮静态复核和 smoke 命令：

```bash
cd wasm-port && ./tools/verify_upstream_baseline.sh
npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run smoke:node
```

## 结论

`ACC-029/INT-016` 已完成 HAL Scope/Meter 源码边界复核。当前可以把 `4.14 HAL Meter` 归为“已有 virtual HAL 基础、需 meter JSON gate 的条件通过”，把 `4.13/10.7 HAL Scope` 归为“原生工具已定位、Web 等效 waveform gate 待实现”。后续不能再用单张 UI 截图或 04 文本中的“通过”直接宣称 HAL Scope 已完整对标 LinuxCNC。