cnc_wams/完善wasm/working/23-04-HAL-Meter-Scope-JSON-Evidence-Gate落地蓝图.md

23-04 HAL Meter/Scope JSON Evidence Gate 落地蓝图

后续状态：本蓝图要求的两个 JSON evidence、wasm-port gate、Web gate 和 compare 字段已由 28 实施完成；原生 halscope/halmeter process 边界不变。

定位

本文件落实 ACC-035/INT-022：在 17-04-HAL-Scope-Meter结构化证据复核.md 和 20-04-HAL-Scope-Meter-JSON-Gate实现缺口复核.md 已经确认缺口之后，进一步把 hal_meter_evidence 与 hal_scope_waveform_evidence 的实际落地路径、数据来源、schema、脚本位置和验收 gate 固定下来。

覆盖 04 条目：

• 4.13 HAL Scope
• 4.14 HAL Meter
• 10.6 HAL 信号监视
• 10.7 HAL Scope

严格口径：halGraph、halNets、gmoccapy HAL model、按钮状态、截图、Canvas 折线或普通 HAL snapshot 只能作为输入来源，不能直接等价为 HAL Meter/Scope 完成。只有生成独立 JSON evidence、通过 Node gate，并在 Web evidence/compare 中引用这些字段，才能把 04 的 HAL Meter/Scope 从“条件通过/待 gate”继续晋级。

LinuxCNC 源码对照

对照对象	LinuxCNC 路径	Web/WASM 等效要求
HAL Meter 当前值监视	linuxcnc/src/hal/utils/meter.c、docs/src/man/man1/halmeter.1.adoc	输出 pin/signal/parameter 当前值、类型、来源、连接状态、source reference 和完整性
HAL Scope 采样组件	linuxcnc/src/hal/utils/scope_rt.c、scope_shm.h、scope_usr.h	输出采样周期、记录长度、通道定义、触发条件、样本序列和 source reference
HAL Scope 用户界面	linuxcnc/src/hal/utils/scope.c、docs/src/hal/halscope.adoc、docs/src/man/man1/halscope.1.adoc	Web 可用 Canvas/表格展示，但 proof 必须落到 waveform JSON
HAL runtime 数据源	linuxcnc/src/hal/hal_lib.c、hal_priv.h	Web/WASM 侧只允许从 LinuxCNC-backed virtual HAL snapshot 或 native evidence 派生，不允许 UI 手填

现有可复用数据源

wasm-port

现有资产	可复用内容	限制
runtime/core/linuxcnc_wrap/linuxcnc_hal_runtime.cpp	snapshot_json() 已输出 pins、signals、params、threads、events	当前不是 hal_meter_evidence 或 hal_scope_waveform_evidence
tests/wasm/node/verify_hal_runtime.mjs	已创建 bit/float/s32/u32 pin、param、net、thread，并断言 snapshot	只证明基础 HAL runtime，不证明 meter/scope schema
lchal_get_snapshot_json	可作为 meter 当前值的数据入口	需新增格式转换和 gate
lchal_step_threads	可作为 scope 采样时钟入口	需记录 samplePeriodNs、recordLength 和样本序列

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

现有资产	可复用内容	限制
app/src/runtime/gmoccapy-hal-model.js	gmoccapy pin group、core/spindle/postgui net、硬按钮/override/jog/tool/message pin 映射	是 HAL model，不是 meter/scope runtime proof
tests/node/verify_gmoccapy_hal_model.mjs	可继续证明 HAL model 本身不漂移	不能替代 hal_meter_evidence/hal_scope_waveform_evidence
working/evidence/web-xyzbc-trt-evidence.json	已有 halGraph、halNets、taskHalFullState、pyvcpPostgui	顶层尚无 hal_meter_evidence、hal_scope_waveform_evidence
working/evidence/compare-xyzbc-trt-evidence.json	已有 native/Web compare 框架	尚无 meter/scope 对比项

本轮复核确认当前 evidence 顶层字段：

web-xyzbc-trt-evidence.json: has_hal_meter_evidence=false
web-xyzbc-trt-evidence.json: has_hal_scope_waveform_evidence=false
compare-xyzbc-trt-evidence.json: has_hal_meter_evidence=false
compare-xyzbc-trt-evidence.json: has_hal_scope_waveform_evidence=false

hal_meter_evidence Schema

建议生成位置：

wasm-port/build/evidence/hal-meter-evidence.json
web-rtcp-5axis-xyzbc-trt-sim-plan/working/evidence/hal-meter-evidence.json

最小 schema：

字段	规则
apiName	固定为 hal_meter_evidence
schemaVersion	固定为 1，后续变更必须增版本
source	wasm-hal-runtime-snapshot、web-task-hal-status 或 native-hal-meter
profileId	例如 xyzbc-trt、xyzac-trt、gmoccapy-xyzab
linuxCncReferences[]	至少包含 src/hal/utils/meter.c 和 docs/src/man/man1/halmeter.1.adoc
snapshotCycle	来源 snapshot 的 cycle/taskCycle/servoCycle
items[]	非空，且至少覆盖 pin、signal、parameter 三类中的可用类别
items[].name	HAL pin/signal/parameter 名称
items[].sourceKind	pin、signal、parameter
items[].type	bit、float、s32、u32、s64、u64
items[].value	与 HAL type 一致的 JSON 值
items[].connected	对 pin/signal 必须有布尔值；parameter 可为 false
items[].signal	pin 连接到 signal 时必须记录
integrity.complete	全部必填字段通过时为 true
integrity.missing[]	缺字段时列出原因，且不得晋级

最小覆盖集合：

pin: motion.analog-out-03, motion.program-line, probe.in/probe.out
signal: probe-signal 或目标 Web evidence 中实际存在的 HAL net signal
parameter: standalone.param-float, standalone.param-s32 或目标 profile 中可回读参数

hal_scope_waveform_evidence Schema

建议生成位置：

wasm-port/build/evidence/hal-scope-waveform-evidence.json
web-rtcp-5axis-xyzbc-trt-sim-plan/working/evidence/hal-scope-waveform-evidence.json

最小 schema：

字段	规则
apiName	固定为 hal_scope_waveform_evidence
schemaVersion	固定为 1
source	wasm-hal-runtime-thread-samples、web-task-hal-servo-samples 或 native-halscope
profileId	与采样运行 profile 一致
linuxCncReferences[]	至少包含 scope_rt.c、scope_shm.h、scope_usr.h、halscope.adoc
samplePeriodNs	正整数
recordLength	正整数
channelCount	必须等于 channels.length
channels[]	每项包含 index、name、kind、type
trigger	包含 mode、channel、edge、level 或显式 forced: true
samples[]	长度等于 recordLength 或记录 integrity.truncated=true
samples[].sampleIndex	从 0 递增
samples[].timeNs	单调递增
samples[].values[]	长度必须等于 channelCount
integrity.complete	字段、长度、类型和时间单调均通过时为 true

最小采样策略：

1. 初始化 HAL runtime，创建至少 2 个 pin 和 1 个 signal。
2. 建立 net，让输出 pin 传播到输入 pin。
3. 每个 sample 前修改至少一个 pin 值，调用一次 lchal_step_threads() 或 Web task/HAL servo step。
4. 记录 sampleIndex、timeNs、每个 channel 的值。
5. 校验至少一个 channel 值随 sample 变化，避免静态截图式 proof。

建议新增 Gate

wasm-port

建议新增：

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

命令：

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

通过输出：

hal_meter_evidence_schema=ok
hal_meter_evidence_items=ok
hal_scope_waveform_schema=ok
hal_scope_waveform_samples=ok

失败条件：

• 没有 linuxCncReferences。
• items[] 或 channels[] 为空。
• samples[] 长度与 recordLength 不一致且没有 truncated 说明。
• waveform 中所有 sample 完全相同。
• 从 UI 字符串或截图生成 evidence，而不是从 HAL snapshot/runtime 派生。

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

建议新增：

web-rtcp-5axis-xyzbc-trt-sim-plan/tests/node/verify_hal_meter_scope_evidence.mjs

并扩展：

web-rtcp-5axis-xyzbc-trt-sim-plan/tools/collect-web-xyzbc-trt-evidence.mjs
web-rtcp-5axis-xyzbc-trt-sim-plan/tools/compare-xyzbc-trt-evidence.mjs

要求：

• web-xyzbc-trt-evidence.json 顶层必须出现 hal_meter_evidence 和 hal_scope_waveform_evidence。
• compare-xyzbc-trt-evidence.json 必须出现对应 comparison 项。
• Browser smoke 只负责证明 UI 渲染，不得替代 JSON schema gate。

04 严格状态更新

04 项	当前状态	落地后晋级条件
4.13 HAL Scope	待实现 waveform JSON gate	生成 hal_scope_waveform_evidence，通过 schema、sample、trigger 和 compare gate
4.14 HAL Meter	条件通过，待补 meter JSON gate	生成 hal_meter_evidence，覆盖 pin/signal/parameter 当前值并通过 gate
10.6 HAL 信号监视	条件通过	如果只声明监视模型，halGraph/halNets 可保留；若声明 meter-like 当前值，必须引用 hal_meter_evidence
10.7 HAL Scope	待实现 waveform JSON gate	Canvas/UI 必须由 hal_scope_waveform_evidence 驱动或引用该 evidence

与现有文件的关系

• 17-04-HAL-Scope-Meter结构化证据复核.md：定义源码边界。
• 20-04-HAL-Scope-Meter-JSON-Gate实现缺口复核.md：确认当前缺 hal_meter_evidence / hal_scope_waveform_evidence。
• 本文件：定义实际 schema、生成路径、脚本位置、通过输出和晋级条件。
• 后续实现脚本后，必须把命令输出回填到 05-验收证据.md，再把 14 中对应项从“待实现 gate”晋级。

结论

ACC-035/INT-022 已完成 HAL Meter/Scope JSON Evidence Gate 的落地蓝图。当前项目仍不能把 04 的 HAL Scope/Meter 宣称为完整完成；但后续实现已收敛为明确的两个 JSON evidence、三个 Node gate 和 Web evidence/compare 字段扩展。任何晋级必须以这些可机读字段和 gate 通过为准。

后续状态

蓝图已由 ACC-040/INT-027 实施：hal_meter_evidence、hal_scope_waveform_evidence、WASM Node gate、Web evidence 和 compare 均已通过。当前严格结论见 28-04-HAL-Meter-Scope-JSON-Evidence-Gate实施记录.md；该结果不继承为原生 GTK/RT halmeter/halscope process proof。