# 20-04 HAL Scope/Meter JSON Gate 实现缺口复核

## 定位

本文件落实 `ACC-032/INT-019`：在 `17-04-HAL-Scope-Meter结构化证据复核.md` 已完成源码边界复核之后，继续检查 `wasm-port` 和 `web-rtcp-5axis-xyzbc-trt-sim-plan` 是否已经具备可执行的 HAL Meter / HAL Scope JSON gate。

覆盖 04 条目：

- `4.13 HAL Scope`
- `4.14 HAL Meter`
- `10.6 HAL 信号监视`
- `10.7 HAL Scope`

严格口径：已有 HAL 模型、HAL graph、postgui net、gmoccapy HAL pin 映射或截图，不能自动等价为 `hal_meter_evidence` / `hal_scope_waveform_evidence`。只有存在结构化 JSON 字段和可执行校验脚本时，才能从“源码边界复核完成”晋级为“JSON gate 已完成”。

## 当前实现复核

### `wasm-port`

已确认存在：

- `wasm-port/tests/wasm/node/verify_hal_runtime.sh`
- `wasm-port/tests/wasm/node/verify_hal_runtime.mjs`
- `wasm-port/tests/wasm/node/verify_task_hal_wasm.sh`
- `wasm-port/tests/wasm/node/verify_motion_hal_sync.sh`

这些 gate 可证明 virtual HAL runtime 的 pin/signal/param/net/thread 基础能力，但当前未发现：

```text
wasm-port/tests/ui/node/verify_hal_meter_evidence.mjs
wasm-port/tests/ui/node/verify_hal_scope_waveform_evidence.mjs
```

因此 `wasm-port` 当前不能把 04 的 `4.13`、`4.14`、`10.7` 晋级为 HAL Scope/Meter JSON gate 完成。

### `web-rtcp-5axis-xyzbc-trt-sim-plan`

已确认存在：

- `web-rtcp-5axis-xyzbc-trt-sim-plan/tests/node/verify_gmoccapy_hal_model.mjs`
- `web-rtcp-5axis-xyzbc-trt-sim-plan/app/src/runtime/gmoccapy-hal-model.js`
- `web-rtcp-5axis-xyzbc-trt-sim-plan/working/evidence/web-xyzbc-trt-evidence.json`
- `web-rtcp-5axis-xyzbc-trt-sim-plan/working/evidence/compare-xyzbc-trt-evidence.json`

`verify_gmoccapy_hal_model.mjs` 可证明：

- gmoccapy HAL 文件、pin group、core net、spindle net、postgui net 的结构化模型存在。
- `gmoccapy.spindle_feedback_bar`、`gmoccapy.spindle_at_speed_led`、`gmoccapy.tooloffset-x`、`gmoccapy.tooloffset-z` 等 postgui net 被登记。
- 硬按钮、jog、override、operator input、tool、program、message 等 gmoccapy HAL pin 映射有 Node smoke。

但当前 evidence JSON 顶层字段只包含 `halGraph`、`halNets`、`taskHalEquivalence`、`taskHalFullState`、`pyvcpPostgui`、`visualEvidence` 等，不包含：

```text
hal_meter_evidence
hal_scope_waveform_evidence
```

因此目标 Web 项目当前可登记为“HAL 模型和 UI 监视有证据”，不能登记为“HAL Meter JSON gate / HAL Scope waveform JSON gate 已完成”。

## LinuxCNC 对照证据

| 对照对象 | 本地 LinuxCNC 路径 | 对 JSON gate 的要求 |
| --- | --- | --- |
| `halmeter` 原生工具 | `linuxcnc/src/hal/utils/meter.c`、`linuxcnc/docs/src/man/man1/halmeter.1.adoc` | 至少输出 pin/signal/parameter 当前值、HAL 类型、来源、完整性和 source reference |
| `halscope` 原生工具 | `linuxcnc/src/hal/utils/scope.c`、`scope_rt.c`、`scope_shm.h`、`scope_usr.h`、`linuxcnc/docs/src/hal/halscope.adoc` | 至少输出 sample period、record length、channel、trigger、sample 序列和 source reference |
| gmoccapy HAL UI 入口 | `linuxcnc/src/emc/usr_intf/gmoccapy/gmoccapy.py`、gmoccapy HAL/Glade 文件 | 只能作为 UI/HAL model 参考，不能替代原生 `halmeter`/`halscope` 数据结构 |

## 必须补齐的 JSON Gate

### `hal_meter_evidence`

最小字段：

| 字段 | 规则 |
| --- | --- |
| `apiName` | 必须等于 `hal_meter_evidence` |
| `source` | `browser-virtual-hal`、`wasm-hal-runtime` 或明确的 native source |
| `items[]` | 非空；每项包含 `name`、`sourceKind`、`type`、`value` |
| `items[].sourceKind` | 只能是 `pin`、`signal`、`parameter` 之一 |
| `integrity.complete` | 必须为 `true` 才能晋级 |
| `integrity.sourceReference` | 必须引用 LinuxCNC `meter.c` 或 `halmeter.1.adoc` |

建议 gate：

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

### `hal_scope_waveform_evidence`

最小字段：

| 字段 | 规则 |
| --- | --- |
| `apiName` | 必须等于 `hal_scope_waveform_evidence` |
| `source` | `browser-virtual-hal`、`wasm-hal-runtime` 或明确的 native source |
| `samplePeriodNs` | 正整数 |
| `recordLength` | 正整数，必须与 `samples.length` 一致或有明确截断原因 |
| `channelCount` | 必须与 `channels.length` 和每个 sample 的 `values.length` 一致 |
| `trigger` | 必须记录 channel/edge/level 或显式 `forced: true` |
| `channels[]` | 每项包含 `index`、`name`、`kind`、`type` |
| `samples[]` | 时间单调；每个 sample 包含 `sampleIndex`、`timeNs`、`values` |
| `sourceReference.linuxcnc[]` | 必须引用 `scope_rt.c`、`scope_shm.h` 或 `halscope.adoc` |

建议 gate：

```bash
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:compare
```

## 当前严格状态

| 04 项 | 当前状态 | 原因 | 晋级条件 |
| --- | --- | --- | --- |
| `4.13 HAL Scope` | 待实现 JSON gate | 原生 `halscope` 源码已定位；当前没有 `hal_scope_waveform_evidence` 字段和校验脚本 | 补 waveform JSON、Node gate、Browser/evidence compare |
| `4.14 HAL Meter` | 条件通过，待补 JSON gate | virtual HAL / gmoccapy HAL model 可支撑当前值来源；当前没有 `hal_meter_evidence` 字段和校验脚本 | 补 meter JSON、Node gate、至少覆盖 pin/signal/parameter 当前值 |
| `10.6 HAL 信号监视` | 条件通过 | `halGraph`、`halNets`、gmoccapy HAL model 可证明监视模型；还不是 meter/scope gate | 若声明 meter-like 功能，必须输出 `hal_meter_evidence` |
| `10.7 HAL Scope` | 待实现 JSON gate | Web evidence 中未见 waveform JSON；截图和 canvas 不可替代 | 补 `hal_scope_waveform_evidence`、字段校验和 UI 渲染 smoke |

## 结论

`ACC-032/INT-019` 已完成实现缺口复核。当前两个目标项目已有 HAL runtime、HAL graph、gmoccapy HAL model 和代表 Web evidence，但未形成 `hal_meter_evidence` / `hal_scope_waveform_evidence` 的可执行 JSON gate。后续不得把 `halGraph`、`halNets`、gmoccapy HAL model、按钮图标或截图直接宣称为 HAL Scope/Meter 完整对标；只有补齐上述 JSON 字段和校验脚本后，04 的 `4.13`、`4.14`、`10.7` 才能继续晋级。